当前位置: 首页 > 工具软件 > cg-docs > 使用案例 >

cgic教程

万博涛
2023-12-01

使用CGIC的基本思路

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

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

  可以看到,整个库实际上就是cgic.c一个文件,可以说是非常得精炼。我们可以把CGIC安装为操作系统的一个动态链接库,这样每次编译的时候,就不需要用到cgic.c。但是由于有特殊需求,我们将修改cgic.c代码,所以不把它安装进系统。每次编译的时候,只要把cgic.ccgic.h放到当前文件夹就好了。
  使用cgic自带cgictest.c来实现第一个C语言CGI程序。你可以新建一个工作目录,用于存放你的CGI程序源代码,把cgic.hcgic.ccgictest.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的值时,就能得到niceCGIC有一族函数帮助我们完成这个任务,比如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中的actionGET还是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.cmain函数中进行了一系列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.cmain中找到相关代码,并修改成上面这样即可。你可以在cgic.c中定义UpSize,也可以在刚才完成的upload.c中定义,然后在cgic.c中用extern方式引用。
  使用BOACGIC上传文件时只能传1MB大小左右,后来发现是BOA搞的鬼,方法有如下2种:

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

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

 类似资料: