cgic教程

万博涛

2023-12-01

使用CGIC的基本思路

C语言编程是一项复杂且容易出错的工作，所以在完成复杂任务时，一定要选择合适的库，对于用C语言编写CGI程序则更是如此。CGIC是非常优秀的C语言CGI库函数，其下载地址为www.boutell.com/cgic/#obtain，现在的版本号是2.05。从上面提供的官方网址下载了CGIC库之后，解开压缩包，里面有大约10个文件，有用的如下：

文件	说明
`cgic.h`	头文件
`cgic.c`	`CGIC`的源代码文件
`cgictest.c`	`CGIC`库的作者提供的一个`CGI`程序例子
`capture.c`	用于调试`CGI`程序的工具
`Makefile`	编译`CGIC`的脚本文件

可以看到，整个库实际上就是cgic.c一个文件，可以说是非常得精炼。我们可以把CGIC安装为操作系统的一个动态链接库，这样每次编译的时候，就不需要用到cgic.c。但是由于有特殊需求，我们将修改cgic.c代码，所以不把它安装进系统。每次编译的时候，只要把cgic.c和cgic.h放到当前文件夹就好了。
使用cgic自带cgictest.c来实现第一个C语言CGI程序。你可以新建一个工作目录，用于存放你的CGI程序源代码，把cgic.h、cgic.c和cgictest.c三个文件拷贝到这个目录，然后建立一个Makefile文件：

test.cgi: cgictest.c cgic.h cgic.c
    gcc -wall cgictest.c cgic.c -o test.cgi

保存好Makefile的内容之后，执行make命令。可以看到当前目录下应该多了一个test.cgi文件。
在你的网站根目录下建立一个cgi-bin目录(当然名字可以任意取，但作为习惯，一般叫做cgi-bin)，然后在Apache的配置文件里赋予其执行CGI代码的权限，权限修改完之后要重启Apache。完成之后，把刚才生成的test.cgi放到cgi-bin目录中。此时我们可以在浏览器中输入以下地址进行访问：

http://127.0.0.1/cgi-bin/test.cgi

如果正常的话，应该看到一个网页被展示出来，这样第一个C语言的CGI程序就运行起来了。
从cgic.c的代码可以看出，它定义了main函数，而在cgictest.c中定义了一个cgiMain函数。也就是说，对于使用CGIC编写的CGI程序，都是从cgic.c中的代码进入，在库函数完成了一系列必要的操作(比如解析参数、获取系统环境变量)之后，它才会调用你的代码(从你定义的cgiMain进入)。另外一点就是，cgi程序输出HTML页面的方式都是使用printf把页面一行一行地打印出来，比如cgictest.c中的这一段代码：

fprintf ( cgiOut, "<textarea NAME="address" ROWS=4 COLS=40>\n" );
fprintf ( cgiOut, "Default contents go here. \n" );
fprintf ( cgiOut, "</textarea>\n" );

上面这段代码的运行结果就是在页面上输出一个textarea。第一个参数cgiOut实际上就是stdin，所以我们可以直接使用printf，而不必使用fprintf。不过在调试的时候会用到fprintf来重定向输出。这种方式与Java Servlet非常类似，Servlet也是通过调用打印语句System.out.println(...)来输出一个页面，不过后来Java推出了JSP来克服这种不便。但是与Servlet不同的地方在于，使用C语言的我们还要自己输出HTML头部(声明文档类型)：

cgiHeaderContentType ( "text/html" );

这个语句的调用一定要在所有printf语句之前。而这个语句执行的任务实际上就是：

void cgiHeaderContentType ( char *mimeType ) {
    fprintf ( cgiOut, "Content-type: %s\r\n\r\n", mimeType );
}

这个语句告诉浏览器，这次传来的数据的类型。如果是个HTML文档，就通过浏览器窗口显示；如果是一个bin(二进制)文件，则打开下载窗口，让用户选择是否保存文件以及保存文件的路径。理解了这几点之后，你就可以编写自己的CGIC程序了：

#include <stdio.h>
#include "cgic.h"
#include <string.h>
#include <stdlib.h>

int cgiMain ( void ) {
    cgiHeaderContentType ( "text/html" );
    fprintf ( cgiOut, "<HTML><HEAD>\n" );
    fprintf ( cgiOut, "<TITLE>My First CGI</TITLE></HEAD>\n" );
    fprintf ( cgiOut, "<BODY><H1>Hello CGIC</H1></BODY>\n" );
    fprintf ( cgiOut, "</HTML>\n" );
    return 0;
}

把Makefile文件中的cgitest.c全部换成test.c，再执行make命令即可。此时通过浏览器访问，会在页面上看到一个大大的Hello CGIC。

获取Get请求字符串

Get请求就是我们在浏览器地址栏输入URL时发送请求的方式，或者我们在HTML中定义一个表单form时，把action属性设为Get时的工作方式。Get请求字符串就是跟在URL后面以问号?开始的字符串，但不包括问号。比如这样的一个请求：

http://127.0.0.1/cgi-bin/out.cgi?ThisIsTheGetString

在上面这个URL中，ThisIsTheGetString就是Get请求字符串。
在进入我们自己编写的cgi代码之前，CGIC库已经事先把这个字符串取到了，我们可以在程序中直接获得，要做的仅仅是在你编写的cgiMain方法前面加入以下声明：

extern char *cgiQueryString;

现在给出一个简单的例子，这个例子跟上一篇的测试程序非常相似，只不过程序的输出是使用者输入的Get请求字符串：

#include <stdio.h>
#include "cgic.h"
#include <string.h>
#include <stdlib.h>

extern char *cgiQueryString;

int cgiMain() {
    cgiHeaderContentType ( "text/html" );
    fprintf ( cgiOut, "<HTML><HEAD>\n" );
    fprintf ( cgiOut, "<TITLE>My CGIC</TITLE></HEAD>\n" );
    fprintf ( cgiOut, "<BODY>" );
    fprintf ( cgiOut, "<H1>%s</H1>", cgiQueryString );
    fprintf ( cgiOut, "</BODY>\n" );
    fprintf ( cgiOut, "</HTML>\n" );
    return 0;
}

假设把这个程序编译成out.cgi，并部署到Web服务器的cgi-bin目录下，当用户在浏览器地址栏输入本文开头给出的URL字符串时，浏览器页面上会显示ThisIsTheGetString。
我们也可以编写一个用于测试的HTML页面：

<html>
    <head>
        <title>Test</title>
    </head>
    <body>
        <form action="cgi-bin/test.cgi" method="get">
            <input type="text" name="theText">
            <input type="submit" value="Continue &rarr;">
        </form>
    </body>
</html>

通过浏览器访问http://127.0.0.1/test.html，在文本框内输入一些字符，并点击提交按钮，然后就可以看到cgi把在文本框输入的字符原样显示在浏览器上。

反转义

浏览器在发送Get请求时，会把请求字符串进行转义操作(英文术语为escape)。比如，我们在地址栏输入(注意最后it's me中的空格)：

http://localhost/~Jack/cgi-bin/out.cgi?it's me

浏览器会把它转义为：

http://localhost/~Jack/cgi-bin/out.cgi?it%27s%20me

在上一篇最后给出的例子中，如果在文本框内输入it's me。你会发现，浏览器最终发送的请求为：

http://localhost/~Jack/cgi-bin/out.cgi?theText=it%27s+me

通过CGIC，可以把这些被转义后的字符还原为我们本来的输入，这个过程就叫反转义(Unescape)。整个过程分三个步骤：
1. 打开cgic.c，找到这一行语句：

static cgiUnescapeResultType cgiUnescapeChars ( char **sp, char *cp, int len );

2. 在这个函数声明语句的上方，你会看到一个结构体定义：

typedef enum {
    cgiUnescapeSuccess,
    cgiUnescapeMemory
} cgiUnescapeResultType;

把这几行语句复制到cgic.h文件中，并在这里把它注释掉。同时还要删除在第一步中找到的函数声明语句中的static关键字。
3. 我们现在就可以使用反转义函数cgiUnescapeChars了。在你自己的代码中，加入以下声明语句：

extern cgiUnescapeResultType cgiUnescapeChars ( char **sp, char *cp, int len );

接下来给出一段完整的test.c代码：

#include <stdio.h>
#include "cgic.h"
#include <string.h>
#include <stdlib.h>

extern char *cgiQueryString;
extern cgiUnescapeResultType cgiUnescapeChars ( char **sp, char *cp, int len );

int cgiMain() {
    char *buffer;
    cgiHeaderContentType ( "text/html" );
    fprintf ( cgiOut, "<HTML><HEAD>\n" );
    fprintf ( cgiOut, "<TITLE>My CGI</TITLE></HEAD>\n" );
    fprintf ( cgiOut, "<BODY>" );
    cgiUnescapeChars ( &buffer, cgiQueryString, strlen ( cgiQueryString ) );
    fprintf ( cgiOut, "<H1>%s</H1>", buffer );
    fprintf ( cgiOut, "</BODY>\n" );
    fprintf ( cgiOut, "</HTML>\n" );
    free ( buffer );
    return 0;
}

值得注意的是，buffer的存储空间是cgiUnescapeChars帮你分配的，但最后要由你自己来释放，这一点千万不可忘记。下面你可以结合上一篇给出的测试用html代码试试该cgi程序的运行结果，也可以直接在浏览器地址栏输入一些带有特殊符号的字符串。
最后讲一下为什么不得不用这种方式来完成该任务，而CGIC不显式提供。CGIC的出发点是，我们平时只需要解析请求中的键值对，比如?q=nice&client=IE，当我们在服务端查询q的值时，就能得到nice。CGIC有一族函数帮助我们完成这个任务，比如cgiFormString。在解析这种请求格式的时候，如果我们提供的参数值含有被转义的字符，那么CGIC就会在内部调用cgiUnescapeChars完成反转义。但是，有时候我们会发送非常复杂的Get请求字符串，但并不是键值对的格式。这就需要直接使用cgiUnescapeChars进行反转义了。例如假设我们有个服务端cgi程序chat.cgi，这是个网络聊天机器人，如果我们发送如下请求：

http://127.0.0.1/cgi-bin/chat.cgi? "this is a cgi user"

那么chat.cgi就会把this is a cgi user当做你对它说的话，经过处理，它会回复一段语句。为了方便，我们并没有写成键值对的形式。这个时候，被我们修改过的的cgiUnescapeChars就能派上用场了。

获取请求中的参数值

我们在提交一个表单form时，怎样把表单内的值提取出来呢？比如下面这个表单：

<form action="cgi-bin/out.cgi" method="POST">
    <input type="text" name="name" />
    <input type="text" name="number" />
    <input type="submit" value="Submit" />
</form>

当out.cgi收到请求时，需要把输入框name和输入框number内的值提取出来，而且不管form中的action是GET还是POST，都要有效。下面给出示例代码：

#include <stdio.h>
#include "cgic.h"
#include <string.h>
#include <stdlib.h>

int cgiMain() {
    char name[241];
    char number[241];
    cgiHeaderContentType ( "text/html" );
    fprintf ( cgiOut, "<HTML><HEAD>\n" );
    fprintf ( cgiOut, "<TITLE>My CGI</TITLE></HEAD>\n" );
    fprintf ( cgiOut, "<BODY>" );
    cgiFormString ( "name", name, 241 );
    cgiFormString ( "number", number, 241 );
    fprintf ( cgiOut, "<H1>%s</H1>", name );
    fprintf ( cgiOut, "<H1>%s</H1>", number );
    fprintf ( cgiOut, "</BODY>\n" );
    fprintf ( cgiOut, "</HTML>\n" );
    return 0;
}

从上面的代码可以看出，第13行和第14行获取了输入框的值。获取输入参数值在CGIC中其实有一族函数，cgiFormString是其中最常用的一个。cgiFormStringNoNewlines用来去掉换行符(如果用户是在一个TextArea里输入字符的话)；cgiFormStringSpaceNeeded用于测试输入值的长度，可以以此为依据，然后按需精确分配缓冲区。

CGI实现文件上传

不少网站都有文件上传的功能，本文展示如何用CGIC库编写文件上传的服务端程序，最后给出一段简单的HTML代码，供大家测试使用。cgi脚本代码如下：

#include <stdio.h>
#include <string.h>
#include <unistd.h>
#include <fcntl.h>
#include <sys/stat.h>
#include "cgic.h"

#define BufferLen 1024

int cgiMain ( void ) {
    cgiFilePtr file;
    int targetFile;
    mode_t mode;
    char name[128];
    char fileNameOnServer[64];
    char contentType[1024];
    char buffer[BufferLen];
    char *tmpStr = NULL;
    int size;
    int got, t;
    // cgiHeaderContentType ( "text/html" );
    printf ( "%s%c%c ", "Content-Type:text/html;charset=utf-8\n\n", 13, 10 );

    /* 取得html页面中file元素的值，应该是文件在客户机上的路径名 */
    if ( cgiFormFileName ( "file", name, sizeof ( name ) ) != cgiFormSuccess ) {
        fprintf ( stderr, "could not retrieve filename/n" );
        goto FAIL;
    }

    cgiFormFileSize ( "file", &size );
    /* 取得文件类型，不过本例中并未使用 */
    cgiFormFileContentType ( "file", contentType, sizeof ( contentType ) );

    /* 目前文件存在于系统临时文件夹中，通常为/tmp，通过该命令打开临时文件。
       临时文件的名字与用户文件的名字不同，所以不能通过路径/tmp/userfilename的方式获得文件 */
    if ( cgiFormFileOpen ( "file", &file ) != cgiFormSuccess ) {
        fprintf ( stderr, "could not open the file/n" );
        goto FAIL;
    }

    t = -1;

    while ( 1 ) { /* 从路径名解析出用户文件名 */
        tmpStr = strstr ( name + t + 1, "//" );

        if ( NULL == tmpStr ) {
            /* if "//" is not path separator, try "/" */
            tmpStr = strstr ( name + t + 1, "/" );
        }

        if ( NULL != tmpStr ) {
            t = ( int ) ( tmpStr - name );
        } else {
            break;
        }
    }

    strcpy ( fileNameOnServer, name + t + 1 );
    mode = S_IRWXU | S_IRGRP | S_IROTH;
    /* 在当前目录下建立新的文件，第一个参数实际上是路径名，
       此处的含义是在cgi程序所在的目录(当前目录)建立新文件 */
    targetFile = open ( fileNameOnServer, O_RDWR | O_CREAT | O_TRUNC | O_APPEND, mode );

    if ( targetFile < 0 ) {
        fprintf ( stderr, "could not create the new file,%s/n", fileNameOnServer );
        goto FAIL;
    }

    /* 从系统临时文件中读出文件内容，并放到刚创建的目标文件中 */
    while ( cgiFormFileRead ( file, buffer, BufferLen, &got ) == cgiFormSuccess ) {
        if ( got > 0 ) {
            write ( targetFile, buffer, got );
        }
    }

    cgiFormFileClose ( file );
    close ( targetFile );
    goto END;
FAIL:
    fprintf ( stderr, "Failed to upload" );
    return 1;
END:
    printf ( "File \"%s\" has been uploaded", fileNameOnServer );
    return 0;
}

假设该文件存储为upload.c，则使用如下命令编译：

gcc -Wall upload.c cgic.c -o upload.cgi

编译完成后，把upload.cgi复制到你部署cgi程序的目录。正式部署时，请务必修改用open创建新文件那一行代码，把open的第一个参数设置为目标文件在服务器上存储的绝对路径，或者相对于cgi程序的相对路径。本例中，出于简单考虑，在cgi程序所在目录下创建新文件。测试用HTML代码如下：

<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        <title>Test Upload</title>
        <meta name="author" content="Jack">
    </head>
    <body>
        <form action="cgi-bin/test.cgi" method="post"
              enctype="multipart/form-data" target="_blank">
            <input type="file" name="file" value="" />
            <input type="submit" name="submit" value="OK">
        </form>
    </body>
</html>

当然，你必须配置cgi脚本程序有权限在cgi-bin目录下创建文件，因为此例把文件上传到cgi-bin目录下。
那么如何控制上传文件的大小呢？因为你有时会不允许用户上传太大的文件。通过分析cgic.c的源代码，我们发现它定义了一个变量cgiContentLength，表示请求的长度。但我们需要首先判断这是一个上传文件的请求，然后才能根据cgiContentLength来检查用户是否要上传一个太大的文件。cgic.c的main函数中进行了一系列if-else判断来检查请求的类型，首先确定这是一个post请求，然后确定数据的编码方式为multipart/form-data。这个判断通过之后，就要开始准备接收数据了。所以我们要在接收数据开始之前使用cgiContentLength判断大小，如果超过标准，就立即返回，不允许继续操作。下面贴出修改后代码片段：

else if ( cgiStrEqNc ( cgiContentType, "multipart/form-data" ) ) {
#ifdef CGICDEBUG
    CGICDEBUGSTART
    fprintf ( dout, "Calling PostMultipartInput\n" );
    CGICDEBUGEND
#endif
    /* UpSize为文件长度上限值，以byte为单位。UpSize是
       一个int变量，因为cgiContentLength的类型为int */
    if ( cgiContentLength > UpSize ) {
        cgiHeaderContentType ( "text/html" );
        printf ( "File too large!\n" );
        cgiFreeResources();
        return -1;
    }

    if ( cgiParsePostMultipartInput() != cgiParseSuccess ) {
#ifdef CGICDEBUG
        CGICDEBUGSTART
        fprintf ( dout, "PostMultipartInput failed\n" );
        CGICDEBUGEND
#endif
        cgiFreeResources();
        return -1;
    }
#ifdef CGICDEBUG
    CGICDEBUGSTART
    fprintf ( dout, "PostMultipartInput succeeded\n" );
    CGICDEBUGEND
#endif
}

变量UpSize表示文件大小的上限。在cgic.c的main中找到相关代码，并修改成上面这样即可。你可以在cgic.c中定义UpSize，也可以在刚才完成的upload.c中定义，然后在cgic.c中用extern方式引用。
使用BOA和CGIC上传文件时只能传1MB大小左右，后来发现是BOA搞的鬼，方法有如下2种：

修改源代码的defines.h里面的宏SINGLE_POST_LIMIT_DEFAULT。
修改boa.conf里面的SinglePostLimit。

实践证明第一种是可以的，然后重新编译生成boa。

cgic教程

使用CGIC的基本思路

获取Get请求字符串

反转义

获取请求中的参数值

CGI实现文件上传

相关阅读

相关文章

相关问答

相关文档