readme.txt

cgi分析

            for (i = 0; i < cgi_numentries("choice"); i++)
            {
              ... cgi_getnentrystr("choice", i) ...
            }

        If "n" is larger than or equal the number of fields named
        "field_name", or is less than 0, the global variable
        "cgi_errno" is set to "CGIERR_N_OUT_OF_BOUNDS".

    int cgi_getentryint(char * field_name)
    --------------------------------------
      Like "cgi_getentrystr()", this function looks for a name/value
      pair named by "field_name".  (In fact, this function is simply
      a wrapper around "cgi_getentrystr()".)

      It returns the integer value of the string value from the form.
      (In other words, it would return the integer 10 if the string
      was "10".)

      If the name/value pair is not found or the string is not an
      integer (for example, "abc" would return the integer 0),
      the global variable "cgi_errno" is set to "CGIERR_NOT_INTEGER".

    int cgi_getnentryint(char * field_name, int n)
    ----------------------------------------------
      Identical to "cgi_getentryint()", but for forms with multiple
      fields with the same name.  See "cgi_getnentrystr()" above
      and "cgi_getnumentries()" below.

    int cgi_getentrydouble(char * field_name)
    -----------------------------------------
      This function is more or less identical to "cgi_getentryint()",
      except it returns a double (floating point).

      If the name/value pair is not found or the string is not an
      integer (for example, "abc" would return the double 0.0),
      the global variable "cgi_errno" is set to "CGIERR_NOT_DOUBLE".

    int cgi_getnentrydouble(char * field_name, int n)
    -------------------------------------------------
      Identical to "cgi_getentrydouble()", but for forms with multiple
      fields with the same name.  See "cgi_getnentrystr()" above
      and "cgi_getnumentries()" below.

    int cgi_getentrybool(char * field_name, int def)
    ------------------------------------------------
      This function returns a "1" or a "0" depending on whether
      the value of the name/value pair you are looking for contains
      the text string "on" or "yes", or "off" or "no", respectively.

      If the name/value pair is not found or the string is not an
      integer (for example, "abc"), the global variable "cgi_errno"
      is set to "CGIERR_NOT_BOOL", and the value returned is "def"
      (a default specified when the function is called).

    int cgi_getnentrybool(char * field_name, int def, int n)
    --------------------------------------------------------
      Identical to "cgi_getentrybool()", but for forms with multiple
      fields with the same name.  See "cgi_getnentrystr()" above
      and "cgi_getnumentries()" below.

    int cgi_getnumentries(char * field_name)
    -----------------------------------------
      Returns how many fields were returned with the name "field_name".
      Use to determine what the maximum value for "n" should be when
      calling cgi_getn...() functions.

    const char * cgi_getcookie(const char * cookie_name)
    ----------------------------------------------------
      Searches the "HTTP_COOKIE" environment variable
      (sent by the browser during the HTTP request) for a particular
      cookie, and returns its value as a string.

      If the cookie is not found, this function returns NULL.

      This function sets the following global variable:

        int cgi_errno
        -------------
          CGIERR_NONE if no errors occured.
          CGIERR_NO_COOKIES if HTTP_COOKIE is not set.
          CGIERR_COOKIE_NOT_FOUND if the cookie wasn't found.
          CGIERR_OUT_OF_MEMORY if it could not create temporary space.

    int cgi_dump_no_abort(char * filename)
    --------------------------------------
      This opens a file and sends it to "stdout" (file descriptor 0),
      which results in the file being sent to the browser.  This is a
      very good way to include standard HTML headers and footers in
      your CGI.  Also, by not embeding the HTML into your C source,
      you no longer need to recompile the CGI after editing that HTML.
      Changes take effect immediately.

      This function sets the following global variable:

        int cgi_errno
        -------------
          CGIERR_NONE if no errors occured.
          CGIERR_CANT_OPEN if the file could not be opened.  (You should
            look at the C global "errno" to determine the exact error.)

      Once the file has been sent out (if it was), the function returns
      with the same value it set "cgi_errno" to.

    void cgi_dump(char * filename)
    ------------------------------
      This function does more or less the same as "cgi_dump_no_abort()"
      (in fact, it's actually a wrapper around that function).

      However, if it cannot open the file, rather than return with an
      error code, this function sends HTML text out stating that it can't
      open the file, including the C "strerror()" description of the error.
      It then aborts your CGI by calling "exit(0);".

      Since most of the time you will be including HTML files which are
      under your control (ie, they are part of the CGI package you are
      creating), you will most often wish to use this function, since it
      is simpler than "cgi_dump_no_abort()" and your HTML files should
      always be available to your CGI.

    void cgi_error(char * reason)
    -----------------------------
      This function displays an HTML error message, starting with the word
      "Error" as a level one header ("<h1>") and followed by the string you
      provide (the actual reason an error occured).

      This function then calls "exit(0);" to abort your CGI.

    int cgi_goodemailaddress(char * addr)
    -------------------------------------
      This function does its best to make sure that a string contains
      a valid-looking e-mail address.  (This is useful for when you
      get users who fill out a form and refuse to enter their e-mail
      address, or they don't understand what their own e-mail address is.
      For example, someone with the address "[e-mail]" might think
      their address is "abc" or "abc@aol" or "abc.aol.col" or even
      "http://[e-mail]".  A good rule: never trust users.)

      A valid e-mail address is in the form:

        [e-mail][.text...]

      In other words, alphanumeric characters ("a-z", "A-Z", "0-9"),
      'dashes' ("-"), underscores ("_") and 'dots' ("."), with exactly one
      'at' ("@") in the middle, and at least one 'dot' appearing after
      the 'at.'  'Dots' and 'ats' are not allowed at the beginning or
      end of the string.

      "cgi_goodemailaddress" returns a "1" if the address appears to be
      in the right format (this does NOT necessarily mean it is a VALID
      address), or "0" if it is not.

    char * cgi_strerror(int err)
    ----------------------------
      Like C's "strerror()" function which returns the text equivalent of
      an "errno" error code, this function returns the text equivalent of
      one of cgi-util's "cgi_errno" error code.


ERROR CODES
-----------
  The many error codes that cgi-util will set "cgi_errno" to are described
  above, but here's a reference:

    CGIERR_NONE
    -----------
      No error occured

    CGIERR_NOT_INTEGER
    ------------------
      The field looked-up by cgi_getentryint() did not exist, or its
      value was not an integer.

    CGIERR_NOT_DOUBLE
    -----------------
      The field looked-up by cgi_getentrydouble() did not exist, or its
      value was not a double.

    CGIERR_NOT_BOOL
    ---------------
      The field looked-up by cgi_getentrybool() did not exist, or its
      value was not "yes", "on", "no" or "off".

    CGIERR_UNKNOWN_METHOD
    ---------------------
      The "REQUEST_METHOD" environment variable was not set to
      "POST" or "GET" (the two understood by cgi-util).

    CGIERR_INCORRECT_TYPE
    ---------------------
      The "CONTENT_TYPE" environment variable was not set to
      "application/x-www-form-urlencoded".

    CGIERR_BAD_CONTENT_LENGTH
    -------------------------
      The "CONTENT_LENGTH" environment variable was not set to
      an integer value.

    CGIERR_CONTENT_LENGTH_DISCREPANCY
    ---------------------------------
      The "CONTENT_LENGTH" environment variable was set to a value
      different from the actual size of data received by cgi_init().

    CGIERR_CANT_OPEN
    ----------------
      The cgi_dump_no_abort() function could not open the file
      specified.  (Check C's "errno" value for the exact reason.)

    CGIERR_OUT_OF_MEMORY
    --------------------
      Space could not be allocated for the data being received by
      cgi_init().


THE TEST PROGRAMS
-----------------
  To understand the test program, first open the "test.html" or
  "filetest.html" HTML file in a web browser.  (You need to open it via the
  HTTP protocol, not simply opening it as a file!)

  With "test.html", you'll notice the following on the page:

    * A type-in field labelled "Name?"
    * A type-in field labelled "Age?"
    * A pull-down menu labelled "Sex?"
    * A submit button labelled "Ok"

  I won't go into the details of creating a form here, since there are
  many, many places where you can learn this.  (If you look at the source
  of "test.html", you'll see some comments which explain what is going on.)

  When you fill out the form and click the "Ok" submit button, the CGI
  will be invoked and you'll see something similar to:

    Hello.
    name=john doe
    age=55
    sex=Male
    Goodbye!

  As you can see, the input you place into the form is echoed back to you
  by this CGI.  To see how this is done, simply look at the source code:
  "test.c"!


  With "filetest.html", you'll see a simpler form:

    * A type-in filed labelled "Name?"
    * A file browse field labelled "File?" (typically these fields appear as
      a type-in form with a "Browse" button next to it)
    * A sumbit button labelled "Ok"

  Select a file from your local filesystem (type it into the type-in field
  or use the "Browse" button, for example), and then submit the form.
  The CGI will be invoked and you'll see something similar to:

    Hello.
    name=john doe
    filename=foo.bar
    This file is 10234 bytes long.
    Goodbye!

  As you can see, the file you uploaded using the form has been processed,
  and the size of the file (in bytes) is displayed by the CGI.  See
  "filetest.c" to see how this CGI works.


THE END
-------
  Hopefully this library will come in useful.  If you have questions or
  comments, please direct them to me:

    [e-mail]

  If you wish to report a bug, use BugTrack:

    http://www.newbreedsoftware.com/bugtrack/


THANKS FOR USING cgi-util!

End of README.txt