putcgi() - set state variable

SYNOPSIS

#include "cgi.h"

int   putcgi(cp, name, val)
CGI  *cp;
char *name, *val;

DESCRIPTION
The putcgi() function sets the state variable name to value val. If name was already set by a putcgi() call during the current invocation, val is added to its value list. The string name should be URL-safe: only alphanumerics, '-' and '_' are allowed. The value string val, however, can contain any characters (ASCII 1-255).

Variables set with putcgi() are immediately visible to getcgi() / cgivar() and have higher precedence than variables from any other list. Thus putcgi() variables supersede any others with the same name, including state variables read from the previous invocation. (Any list's variables are still accessible by explicitly giving its flag, however, e.g. CGI_URL for URL variables.)

The cgiwritestate() function must be called after the last putcgi(), to save the state variables for the next invocation of the CGI program. Only variables set with putcgi() during the current invocation will be saved; the previous state variables will be lost if not explicitly re-written with putcgi(). (If no putcgi() calls are made at all, however, the state will not be changed.)

putcgi() returns the current number of values set for the variable, or 0 on error.

CAVEATS
Note that every state variable must be re-saved with putcgi() during each invocation or it is lost. Also, since the internal variable lists are modified, any previously returned values from getcgi() or cgivar() should be considered invalid.