getcgi() - get CGI variable

SYNOPSIS

#include "cgi.h"

char  **getcgi(cp, name, which)
CGI    *cp;
char   *name;
int     which;

DESCRIPTION
The getcgi() function looks for a CGI variable with the name pointed to by name, and returns its value(s). If no such CGI variable is set, CHARPPN is returned. Since there may be more than one value to the variable (e.g. for a multiple-select form variable), a ""-terminated string list is returned. The list is associated with the CGI object and will be freed when the object is closed. All returned values are decoded from whatever their source is (i.e. URL vars are URL-decoded).

The which parameter indicates which of the CGI variable lists to search. It is a bitwise-OR combination of any the following flags:

CGI_PUT for state variables set with putcgi() during this invocation
CGI_PREVPUT for state variables set from previous invocations
CGI_COOKIE for cookie variables
CGI_ENV for environment variables
CGI_URL for variables encoded in the URL
CGI_CONTENT for variables encoded via the POST method (i.e. content variables from a form)

In addition, there are some shorthand flags:

CGI_STATE for any state variable (equivalent to CGI_PUT|CGI_PREVPUT)
CGI_ANY for any variable from any list

If a variable occurs in more than one of the specified lists (e.g. in the environment and URL), only the values in the first list in which the variable is found are returned. The lists are searched in the order given above, i.e. state variables first, then cookie, environment, URL, and content variables. Since state variables have the highest precedence, they will always be found before variables sent by the Web client; this ensures that state variables saved by the CGI program can't be "hidden" by client-sent variables.

EXAMPLE

#include "cgi.h"

CGI  *cp;

...

{
  char   **vals;

  vals = getcgi(cp, "PATH", CGI_ENV); /* check environment for PATH */
  if (vals != CHARPPN) printf("PATH is: %s\n", *vals);
  else printf("No PATH set in the environment\n");
  /* MAGIC might be a form variable sent via POST or GET methods */
  vals = getcgi(cp, "MAGIC", CGI_ANY);
  if (vals != CHARPPN) {
    printf("MAGIC is:");
    for ( ; **vals; vals++) printf(" %s", *vals);
    printf("\n");
  }
}

CAVEATS
The returned string list is not allocated to the caller, and should not be freed or modified; it is associated with the CGI object. The list may change after certain API calls that affect CGI variables (e.g. putcgi(), closecgi(), cgiprocenv()) and should be assumed invalid after such calls.