cgi_debug_init initializes a CGI program for standalone
debugging. By running a ClearSilver CGI program with a
filename on the command line as the first argument, the
CGI program will load that file of the form K=V as a set
of HTTP/CGI environment variables. This allows you to
run the program under a debugger in a reproducible
environment.
None

We split cgi_init into two sections, one that parses
just the basics, and the second is cgi_parse. cgi_parse
is responsible for parsing the entity body of the HTTP
request. This payload is typically only sent (expected)
on POST/PUT requests, but generally this is called on
all incoming requests. This function walks the list of
registered parse callbacks (see cgi_register_parse_cb),
and if none of those matches or handles the request, it
Either data populated into files and cgi->hdf, or whatever
other side effects of your own registered callbacks.

Arguments:

cgi - a pointer to a CGI pointer

Output:

Either data populated into files and cgi->hdf, or whatever
other side effects of your own registered callbacks.

cgi_destroy will destroy all the data associated with a
CGI, which mostly means the associated HDF and removal
of any files that were uploaded via multipart/form-data.
(Note that even in the event of a crash, these files
will be deleted, as they were unlinked on creation and
only exist because of the open file pointer)
cgi - NULL on output

cgi_register_strfuncs is a helper function which
registers all of the CGI specific string functions on
the given CSPARSE. These include url_escape,
html_escape, text_html, js_escape, html_strip,
url_validate, css_url_validate and null_escape.
None

cgi_url_validate will check that a URL starts with
one of the accepted safe schemes.
If not, it returns "#" as a safe substitute.
Currently accepted schemes are http, https, ftp and mailto.
It then html escapes the entire URL so that it is safe to
insert in an href attribute.
esc - a newly allocated string

cgi_url_escape_more will do URL escaping on the passed in
string, and return a newly allocated string that is escaped.
Characters which are escaped include control characters,
%, ?, +, space, =, &, /, and " and any characters in
other
esc - a newly allocated string

Arguments:

buf - a 0 terminated string
other - a 0 terminated string of characters to escape

cgi_redirect will redirect the user to another page on
your site. This version takes only the path portion of
the URL. As with all printf style commands, you should
not call this with arbitrary input that may contain %
characters, if you are forwarding something directly,
use a format like cgi_redirect (cgi, "%s", buf)
None

The ClearSilver CGI Kit has built-in functionality to handle
the following methods:
GET -> doesn't have any data except query string, which
is processed for all methods
POST w/ application/x-www-form-urlencoded
POST w/ multipart/form-data
processed as RFC2388 data into files and HDF (see
cgi_filehandle())
PUT (any type)
The entire data chunk is stored as a file, with meta
data in HDF (similar to single files in RFC2388).
The data is accessible via cgi_filehandle with NULL
for name.
To handle other methods/content types, you have to
register your own parse function. This isn't necessary
if you aren't expecting any data, and technically HTTP
only allows data on PUT/POST requests (and presumably
user defined methods). In particular, if you want to
implement XML-RPC or SOAP, you'll have to register a
callback here to grab the XML data chunk. Usually
you'll want to register POST w/ application/xml or POST
w/ text/xml (you either need to register both or
register POST w/ * and check the ctype yourself,
remember to nerr_raise(CGIParseNotHandled) if you aren't
handling the POST).
In general, your callback should:
Find out how much data is available:
l = hdf_get_value (cgi->hdf, "CGI.ContentLength", NULL);
len = atoi(l);
And read/handle all of the data using cgiwrap_read.
See the builtin handlers for how this is done. Note
that cgiwrap_read is not guarunteed to return all of
the data you request (just like fread(3)) since it
might be reading of a socket. Sorry.
You should be careful when reading the data to watch
for short reads (ie, end of file) and cases where the
client sends you data ad infinitum.
None

Arguments:

cgi - a CGI struct
method - the HTTP method you want to handle, or * for all
ctype - the HTTP Content-Type you want to handle, or * for all
rock - opaque data that we'll pass to your call back

cgi_url_escape will do URL escaping on the passed in
string, and return a newly allocated string that is escaped.
Characters which are escaped include control characters,
%, ?, +, space, =, &, /, and "
esc - a newly allocated string

cgi_init initializes the ClearSilver CGI environment,
including creating the HDF data set. It will then import
the standard CGI environment variables into that dataset,
will parse the QUERY_STRING into the data set, and parse
the HTTP_COOKIE into the data set. Note that if the
var xdisplay is in the form data, cgi_init will attempt
to validate the value and launch the configured debugger
on the CGI program. These variables have to be
specified in the hdf_file pointed to by hdf_file. The
default settings do not allow debugger launching for
security reasons.
cgi - an allocated CGI struct, including

Arguments:

cgi - a pointer to a CGI pointer
hdf_file - the path to an HDF data set file that will also be
loaded into the dataset. This will likely have to
a be a full path, as the HDF search paths are not
yet set up. Certain things, like

cgi_redirect_uri will redirect the user to another page on
your site. This version takes the full URL, including
protocol/domain/port/path.
As with all printf style commands, you should
not call this with arbitrary input that may contain %
characters, if you are forwarding something directly,
use a format like cgi_redirect (cgi, "%s", buf)
None

cgi_cookie_clear will send back a Set-Cookie string that
will attempt to stop a browser from continuing to send
back a cookie. Note that the cookie has to match in
name, domain, and path, and the luck of the Irish has to
be with you for this work all the time, but at the least
it will make the browser send back a cookie with no
value, which the ClearSilver cookie parsing code will
ignore.
None

Arguments:

cgi - a CGI struct
name - the cookie name to clear
domain - the domain to clear, NULL for none
path - the cookie's path

cgi_cookie_set will issue a Set-Cookie header that
should cause a browser to return a cookie when required.
Note this function does no escaping of anything, you
have to take care of that first.
None

Arguments:

cgi - a CGI struct
name - the name of the cookie
value - the value to set the cookie to.
path - optional path for which the cookie is valid. Default
is /
domain - optional domain for which the cookie is valid. You
can use cgi_cookie_authority to determine this
domain. Default is none, which is interpreted by
the browser as the sending domain only.
time_str - expiration time string in the following format

cgi_css_url_validate will check that a URL is safe against XSS
by verifying that it is relative, or that it starts with
one of the accepted safe schemes. If not, it returns "#" as
a safe substitute. Currently accepted schemes are http, https,
ftp and mailto. It then escapes the entire URL so that the URL
is safe inside @import statements or in a CSS property such as
esc - a newly allocated string

cgi_cookie_authority will walk the CookieAuthority
portion of the CGI HDF data set, and return the matching
domain if it exists. The purpose of this is so that you
set domain specific cookies. For instance, you might
have
CookieAuthority.0 = neotonic.com
In which case, any webserver using a hostname ending in
neotonic.com will generate a cookie authority of
neotonic.com.
None

Arguments:

cgi - a CGI struct
host - optional host to match against. If NULL, the function
will use the HTTP.Host HDF variable.

cgiwrap_iterenv allows a program to iterate over all the
environment variables. This is probably mostly used by
the default debug output.
k - a malloc'd copy of the variable name
v - a malloc'd copy of the variable value

Arguments:

n - variable to return. This should start at 0 and increment
until you receive a NULL return value.

Output:

k - a malloc'd copy of the variable name
v - a malloc'd copy of the variable value

cgiwrap_putenv wraps the putenv call. This is mostly
used by the cgi_debug_init function to create an
artificial environment. This version differs from the
system version by having separate arguments for the
variable name and value, which makes life easier for the
caller (usually), and keeps most wrapping callbacks from
having to implement a parser to separate them.
None

cgiwrap_init_emu sets up the cgiwrap subsystem for use
in an emulated environment where you are providing
routines to use in place of the standard routines, ie
when used to interface with a server or scripting
language.
See cgi/cgiwrap.h for the exact definitions of the
callback functions.
None

cgiwrap_init_std will initialize the cgiwrap subsystem
to use the default CGI functions, ie
getenv/putenv/stdio. In reality, all this is doing is
setting up the data for the cgiwrap_iterenv() function.
None

cgiwrap_getenv wraps the getenv function for access to
environment variables, which are used to pass data to
CGI scripts. This version differs from the system
getenv in that it makes a copy of the value it returns,
which gets around problems when wrapping this routine in
garbage collected/reference counted languages by
moving the ownership of the data to the calling
function.
v - a newly allocated copy of the value of that variable, or
NULL if not found.

Arguments:

k - the environment variable to lookup

Output:

v - a newly allocated copy of the value of that variable, or
NULL if not found.

cs_destroy will clean up all the memory associated with
a CSPARSE structure, including strings passed to
cs_parse_string. This does not clean up any memory
allocated by your own CSOUTFUNC or the HDF data
structure passed to cs_init. It is safe to call this
with a NULL pointer, and it will leave parse NULL as
well (ie, it can be called more than once on the same
var)
parse - will be NULL

cs_render will evaluate a CS parse tree, calling the
CSOUTFUNC passed to it for output. Note that calling
cs_render multiple times on the same parse tree may or
may not render the same output as the set statement has
side-effects, it updates the HDF data used by the
render. Typically, you will call one of the cs_parse
functions before calling this function.
None

Arguments:

parse - the CSPARSE structure containing the CS parse tree
that will be evaluated
ctx - user data that will be passed as the first variable to
the CSOUTFUNC.
cb - a CSOUTFUNC called to render the output. A CSOUTFUNC is
defined as:
typedef NEOERR* (*CSOUTFUNC)(void *, char *);

parse - a pointer to a CSPARSE structure initialized with cs_init()
funcname - the name for the CS function call
Note that registering a duplicate funcname will
raise a NERR_DUPLICATE error
str_func - a CSSTRFUNC not-callback

cs_register_fileload registers a fileload function that
overrides the built-in function. The built-in function
uses hdf_search_path and ne_file_load (based on stat/open/read)
to find and load the file on every template render.
You can override this function if you wish to provide
other template search functions, or load the template
from an in-memory cache, etc.
This fileload function will be used by cs_parse, including
None

Arguments:

parse - a pointer to an initialized CSPARSE structure
ctx - pointer that is passed to the CSFILELOAD function when called
fileload - a CSFILELOAD function

cs_init will create a CSPARSE structure and initialize
it. This structure maintains the state and information
necessary for parsing and rendering a CS template.
parse will contain a pointer to the allocated CSPARSE
structure. This structure will be deallocated with
cs_destroy()

Arguments:

parse - a pointer to a pointer to a CSPARSE structure that
will be created
hdf - the HDF dataset to be used during parsing and rendering

Output:

parse will contain a pointer to the allocated CSPARSE
structure. This structure will be deallocated with
cs_destroy()

cs_register_strfunc will register a string function that
can be called during CS render. This not-callback is
designed to allow for string formating/escaping
functions that are not built-in to CS (since CS is not
HTML specific, for instance, but it is very useful to
have CS have functions for javascript/html/url
escaping). Note that we explicitly don't provide any
associated data or anything to attempt to keep you from
using this as a generic callback...
The format of a CSSTRFUNC is:
NEOERR * str_func(char *in, char **out);
This function should not modify the input string, and
should allocate the output string with a libc function.
(as we will call free on it)

Arguments:

parse - a pointer to a CSPARSE structure initialized with cs_init()
funcname - the name for the CS function call
Note that registering a duplicate funcname will
raise a NERR_DUPLICATE error
str_func - a CSSTRFUNC not-callback

cs_parse_string parses a string. The string is
modified, and internal references are kept by the parse
tree. For this reason, ownership of the string is
transfered to the CS system, and the string will be
free'd when cs_destroy() is called.
The parse information will be appended to the current
parse tree. During parse, the only HDF variables which
are evaluated are those used in evar or include
statements.
None

Arguments:

parse - a CSPARSE structure created with cs_init
buf - the string to parse. Embedded NULLs are not currently
supported
blen - the length of the string

cs_parse_file will parse the CS template located at
path. It will use hdf_search_path() if path does not
begin with a '/'. The parsed CS template will be
appended to the current parse tree stored in the CSPARSE
structure. The entire file is loaded into memory and
parsed in place.
None

Arguments:

parse - a CSPARSE structure created with cs_init
path - the path to the file to parse

Registers a function the same way as cs_register_function, but
disables auto escaping for the output of the function.

Arguments:

parse - a pointer to a CSPARSE structure initialized with cs_init()
funcname - the name for the CS function call
Note that registering a duplicate funcname will
raise a NERR_DUPLICATE error
n_args - expected number of argument for funcname
function - callback of type CSFUNCTION, to handle the registered
function.

Can be used to iterate through values in the dictionary.
The order is the order of the hash of the ids, which
isn't usefully externally. Will return the value if
found, or NULL if not. If <plock> is non-NULL, then
the lock returned in <plock> will be associated with
the returned value. Until this lock is passed to
dictReleaseLock(), the value will not be passed to the
dictCleanupFunc callback (see dictCleanup()).
plock - set to value lock.
id - pointer to id of found value

Arguments:

dict - dictionary to iterate over.
id - pointer to identifier of last item found, or
pointer to NULL to retrieve first.
plock - place for value lock (or NULL).

Finds <id>'s value and calls <update>. If <id> is
not in <dict>, calls <new> to obtain a new value.
None.

Arguments:

dict - dictionary to add pair to.
id - identifier of value
new - function to call to create new value (may be NULL)
update - function to call to modify value (if NULL, the old
value is freed, and <new> is used)
rock - context to pass to <new> or <update>.

Searches for <id> in <dict>, and returns value if
found, or NULL if not. If <plock> is non-NULL, then
the lock returned in <plock> will be associated with
the returned value. Until this lock is passed to
dictReleaseLock(), the value will not be passed to the
dictCleanupFunc callback (see dictCleanup()).
plock - set to value lock.

filter_wait wraps the waitpid call and raises an error
(with description) if the call failed. Note that if the
ask for the exitcode and the process exited with a code
other than zero, we don't raise an error. If you don't
ask for the exitcode, and it is non-zero, we raise an
error
exitcode -> the exitcode if the process existed normally

Arguments:

pid -> the process identifier to wait for
options -> the options to pass to waitpid (see wait(2))

filter_create_fp is identical to filter_create_fd,
except each of the pipes is wrapped in a buffered stdio FILE
in -> the stdin FILE of the sub process
out -> the stdout FILE of the sub process
err -> the stderr FILE of the sub process
pid -> the pid of the sub process

Arguments:

cmd -> the sub command to execute. Will be executed with
/bin/sh -c
in -> pointer to return the stdin pipe, or NULL if you don't
want the stdin pipe
out -> pointer to return the stdout pipe, or NULL if you don't
want the stdout pipe
ferr -> pointer to return the stderr pipe, or NULL if you don't
want the stderr pipe

Output:

in -> the stdin FILE of the sub process
out -> the stdout FILE of the sub process
err -> the stderr FILE of the sub process
pid -> the pid of the sub process

filter_create_fd and filter_create_fp are what popen
fdin -> the stdin file descriptor of the sub process
fdout -> the stdout file descriptor of the sub process
fderr -> the stderr file descriptor of the sub process
pid -> the pid of the sub process

Arguments:

cmd -> the sub command to execute. Will be executed with
/bin/sh -c
fdin -> pointer to return the stdin pipe, or NULL if you don't
want the stdin pipe
fdout -> pointer to return the stdout pipe, or NULL if you don't
want the stdout pipe
fderr -> pointer to return the stderr pipe, or NULL if you don't
want the stderr pipe

Output:

fdin -> the stdin file descriptor of the sub process
fdout -> the stdout file descriptor of the sub process
fderr -> the stderr file descriptor of the sub process
pid -> the pid of the sub process

neos_auto_escape takes an auto-escape context, determines the
escaping modifications needed to make input safe in that context.
It applies these modifications to the input string. It will
first determine if any modifications are necessary, if not - the
input string is returned as output.
esc -> the escaped string will be returned in this pointer.
do_free -> if *do_free is true, *esc should be freed. If not, *esc
contains str and should not be freed.

Takes a MIME type header, and configures the underlying
htmlparser object to expect input of the corresponding type.
This functionality is provided for situations where the html
parser cannot itself determine the proper starting context of
the input, for instance - when a javascript source file or a
stylesheet is being parsed.
This function should be called before any input is processed
using neos_auto_parse().
None.
*

nerr_pass_ctx - - pass a clearsilver error up a level in the call
chain with additional information

this function is used to pass an error up a level in the
call chain (ie, if the error isn't handled at the
current level). This allows us to track the traceback
of the error.
This version includes context information about lower
errors

Arguments:

with the macro, the function name, file and lineno are
automagically recorded. Just pass the error and
a printf format string giving more information about where
the error is occuring.

initialize the NEOERR system. Can be called more than once.
This registers all of the built in error types as defined at
the top of this file. If you don't call this, all exceptions
will be returned as UnknownError.

nerr_match is used to walk the NEOERR chain and match
the error against a specific error type. In exception
parlance, this would be the equivalent of "catch".
Typically, you can just compare a NEOERR against STATUS_OK
or just test for true if you are checking for any error.

Arguments:

err - the NEOERR that has an error.
type - the NEOERR type, as registered with nerr_register

Use this method to create an error "exception" for
return up the call chain

Arguments:

using the macro, the function name, file, and lineno are
automagically recorded for you. You just provide the
error (from those listed above) and the printf-style
reason. THIS IS A PRINTF STYLE FUNCTION, DO NOT PASS
UNKNOWN STRING DATA AS THE FORMAT STRING.

hdf_set_symlink creates a link between two sections of
an HDF dataset. The link is "by name" hence the term
"symlink". This means that the destination node does
not need to exist. Any attempt to access the source
node will cause the function to walk to the dest node,
and then continue walking from there. Using symlinks
can "hide" values in the dataset since you won't be able
to access any children of the linked node directly,
though dumps and other things which access the data
structure directly will bypass the symlink. Use this
feature sparingly as its likely to surprise you.
None

Arguments:

hdf -> the dataset node
src -> the source node name
dest -> the destination node name (from the top of the
dataset, not relative names)

hdf_get_valuef walks the data set pointed to by hdf via
namefmt printf expanded with varargs, and returns the
string value located there, or NULL if it doesn't exist.
This differs from hdf_get_value in that there is no
default value possible.
None

hdf_get_int_value walks the HDF data set pointed to by
hdf to name, and returns the value of that node
converted to an integer. If that node does not exist,
or it does not contain a number, the defval is returned.
None

Arguments:

hdf -> a node in an HDF data set
name -> the name of a node to walk to in the data set
defval -> value to return in case of error or if the node
doesn't exist

hdf_get_node - - Similar to hdf_get_obj except all the nodes
are created if the don't exist.

NEOERR * hdf_get_node (HDF *hdf, const char *name, HDF **ret);

hdf_get_node is similar to hdf_get_obj, except instead
of stopping if it can't find a node in the tree, it will
create all of the nodes necessary to hand you back the
node you ask for. Nodes are created with no value.
ret -> the dataset node you asked for

hdf_set_value will set the value of a named node. All
of the interstitial nodes which don't exist will be
created with a value of NULL. Existing nodes are not
modified. New nodes are created at the end of the list.
If a list of nodes exceeds FORCE_HASH_AT, then a HASH
will be created at that level and all of the nodes will
be added to the hash for faster lookup times.
The copy of the value will be made which the dataset
will own.
None

Arguments:

hdf -> the pointer to the hdf dataset
name -> the named node to walk to
value -> the value to set the node to

hdf_obj_child and the other hdf_obj_ functions are
accessors to the HDF dataset. Although we do not
currently "hide" the HDF struct implementation, we
recommend you use the accessor functions instead of
accessing the values directly.
None

hdf_set_buf is similar to hdf_set_value, except the
dataset takes ownership of the value instead of making a
copy of it. The dataset assumes that value was
malloc'd, since it will attempt to free it when
hdf_destroy is called
None

Arguments:

hdf -> the hdf dataset node
name -> the name to walk to
value -> the malloc'd value

hdf_register_fileload registers a fileload function that
overrides the built-in function. The built-in function
uses hdf_search_path and ne_file_load (based on stat/open/read)
to find and load the file on every hdf_read_file (including
#include). You can override this function if you wish to provide
other file search functions, or load the hdf file
from an in-memory cache, etc.
None

Arguments:

hdf - pointer to a head HDF node
ctx - pointer that is passed to the HDFFILELOAD function when called
fileload - a HDFFILELOAD function

hdf_obj_top is an accessor function which returns a
pointer to the top of the dataset, the node which was
returned by hdf_init. This is most useful for
implementations of language wrappers where individual
nodes are tied garbage colletion wise to the top node of
the data set
None

hdf_destroy is used to deallocate all memory associated
with an hdf data set. Although you can pass an HDF node
as an argument to this function, you are likely to cause
a segfault if you continue to access the data set. In
the future, we may restrict hdf_destroy so it only works
on the top level node.
None

hdf_obj_value is an accessor function for a dataset node
which returns the value of the node, or NULL if the node
has no value. This is not a copy of the value, so the
node retains ownership of the value
None

hdf_sort_obj will sort the children of an HDF node,
based on the given comparison function.
This function works by creating an array of the pointers
for each child object of h, using qsort to sort that
array, and then re-ordering the linked list of children
to the new order. The qsort compare function uses a
pointer to the value in the array, which in our case is
a pointer to an HDF struct, so your comparison function
should work on HDF ** pointers.
None (h children will be sorted)

hdf_set_valuef is a convenience function that wraps
hdf_set_value. Due to limitations of C, the fmt is in
the format "name=value", where we will first format the
entire string, and then break it at the first (from the
left) equal sign (=) and use the left portion as the
name and the right portion as the value. This function
is somewhat inefficient in that it first allocates the
full name=value, and then the call to hdf_set_value
duplicates the value portion, and then we free the
name=value.
Currently, we don't strip whitespace from the key or
value. In the future, this function might work more
like reading a single line of an HDF string or file,
allowing for attributes and symlinks to be specified...
maybe.
None

hdf_get_valuevf walks the data set pointed to by hdf via
namefmt printf expanded with varargs ap, and returns the
string value located there, or NULL if it doesn't exist.
This differs from hdf_get_value in that there is no
default value possible.
None

hdf_search_path is a convenience/utility function that
searches for relative filenames in a search path. The
search path is the list given by the children of
hdf.loadpaths.
full -> the full path of the file

Arguments:

hdf -> the hdf dataset to use
path -> the relative path
full -> a pointer to a buffer
full_len -> size of full buffer

Inserts the <key>/<value> pair into the <list>.
Key values 0 and -1 are reserved (and illegal).
If key is already in list, and <allowUpdate> is true,
value is updated, otherwise SKIPERR_EXISTS is returned.
None.

Searches for <key> in <list>, and returns value if
found, or NULL if not. If <plock> is non-NULL, then
the lock returned in <plock> will be associated with
the returned value. Until this lock is passed to
skipRelease(), the value will not be freed with the
freeValue callback (see skipNewList()).
plock - set to value lock.

Searches in list <list> for item with key next larger
that the one in <pkey>, and returns its value if
found, or NULL if not. If <plock> is non-NULL, then
the lock returned in <plock> will be associated with
the returned value. Until this lock is passed to
skipRelease(), the value will not be freed with the
freeValue callback (see skipNewList()).
pkey - set to new key.
plock - set to value lock.

Returns a new skip list. If <threaded> is true, list is
multi-thread safe. <root> and <maxLevel> determine
performance and expected size (see discussion above).
<flushLimit> is for threaded lists and determines the
maximum number of deleted items to keep cached during
concurrent searches. Once the limit is reached, new
concurrent reads are blocked until all deleted items are
flushed.
None.

this function returns the key and column names for the
current database
primary_key - pointer to the primary key
data - pointer to a ULIST of the columns.
both of these are allocated structures, you can clear data
with uListDestroy (data, ULIST_FREE)

Arguments:

wdb - open database

Output:

primary_key - pointer to the primary key
data - pointer to a ULIST of the columns.
both of these are allocated structures, you can clear data
with uListDestroy (data, ULIST_FREE)