int cgiwritestate(cp, tofile)
cgiwritestate() function saves the current invocation's
state variables (set by
putcgi()) by generating an encrypted
cookie containing them. The cookie will be returned by the client's
Web browser on future invocations, enabling the API to retrieve the
state variables from it. A
Set-Cookie header is printed to set
tofile is non-zero, the state variables are instead saved
to a local file, and the cookie becomes a handle to them. This is
useful if the number and size of state variables is expected to be
large, greater than about 4k, though it does incur some file I/O
(usually 1 read & 1 write).
As it prints an HTTP header,
cgiwritestate() must be called
cgiendhdrs(), yet after all
putcgi() calls. It returns 1 if ok, 0 on error, or -1 if the
invoking Web browser isn't recognized as one that supports cookies: in
cgigetstate() must be used to send the state cookie
in the URL or a form variable.
A CGI program must always keep the same value for the
flag, either non-zero or zero. If it is changed from one invocation
to the next the state variables may be lost.
may return an error if it is not called during headers (between
cgiendhdrs()), or if called more than
once during an invocation.