ClearSilver C API

Documentation
Overview
Why Clearsilver?
Clearsilver Basics
   HDF Dataset
   Template Syntax
      Expressions
      Macros
      Functions
   CGI Kit
      Config Vars
   FAQ
API Reference
   Concepts
   C API
   Python API
      Introduction
   Perl API
   Java API
Tools

Comparison with PHP, ASP, JSP
Comparison with XML/XSLT

API Functions

cgi_filehandle	cgi_debug_init	cgi_register_parse_cb	cgi_url_escape	cgi_parse
cgi_destroy	cgi_init	cgi_redirect_uri	cgi_output	cgi_cookie_clear
cgi_redirect	cgi_url_unescape	cgi_vredirect	cgi_cs_init	cgi_display
cgi_error	cgi_cookie_set	cgi_url_escape_more	cgi_neo_error	cgi_cookie_authority
cgiwrap_writevf	cgiwrap_write	cgiwrap_read	cgiwrap_iterenv	cgiwrap_putenv
cgiwrap_init_emu	cgiwrap_getenv	cgiwrap_init_std	cgiwrap_writef	cs_dump
cs_destroy	cs_render	cs_parse_string	cs_init	cs_parse_file
cs_register_strfunc	dictReleaseLock	dictRemove	dictNext	dictDestroy
dictCreate	dictSetValue	dictModifyValue	dictSearch	dictCleanup
filter_wait	filter_create_fp	filter_create_fd	nerr_pass	nerr_log_error
nerr_pass_ctx	nerr_ignore	nerr_raise	hdf_set_symlink	hdf_get_valuef
hdf_read_string	hdf_obj_value	hdf_get_node	hdf_sort_obj	hdf_write_file_atomic
hdf_obj_attr	hdf_set_valuef	hdf_search_path	hdf_set_attr	hdf_dump_str
hdf_get_int_value	hdf_read_string_ignore	hdf_get_copy	hdf_copy	hdf_write_file
hdf_get_valuevf	hdf_set_value	hdf_set_int_value	hdf_dump	hdf_get_value
hdf_set_copy	hdf_obj_child	hdf_obj_next	hdf_set_buf	hdf_write_string
hdf_get_obj	hdf_get_attr	hdf_obj_name	hdf_obj_top	hdf_dump_format
hdf_get_child	hdf_destroy	hdf_remove_tree	hdf_init	skipInsert
skipDelete	skipSearch	skipNext	skipFreeList	skipNewList
skipRelease	mCreate	fCreate	mUnlock	cBroadcast
fUnlock	cSignal	fFind	cDestroy	cCreate
mLock	cWait	fLock	fDestroy	mDestroy
wdb_keys

cgi_filehandle - - return a file pointer to an uploaded file

FILE *cgi_filehandle (CGI *cgi, char *form_name);

cgi_filehandle will return the stdio FILE pointer
associated with a file that was uploaded using
multipart/form-data. The FILE pointer is positioned at
the start of the file when first available. None

Arguments:	cgi - a pointer to a CGI struct allocated with cgi_init form_name - the form name that the file was uploaded as (not the filename) (if NULL, we're asking for the file handle for the PUT upload)
Output:	None

cgi_debug_init - - initialize standalone debugging

void cgi_debug_init (int argc, char **argv);

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

Arguments:	argc/argv - the arguments from main
Output:	None

cgi_register_parse_cb - - Register a parse callback

NEOERR *cgi_register_parse_cb(CGI *cgi, char *method, char *ctype, void *rock, 

  CGI_PARSE_CB parse_cb);

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
Output:	None

cgi_url_escape - - url escape a string

NEOERR *cgi_url_escape (unsigned char *buf, unsigned char **esc);

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

Arguments:	buf - a 0 terminated string
Output:	esc - a newly allocated string

cgi_parse - - Parse incoming CGI data

NEOERR *cgi_parse (CGI *cgi);

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 - - deallocate the data associated with a CGI

void cgi_destroy (CGI **cgi);

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

Arguments:	cgi - a pointer to a pointer to a CGI struct
Output:	cgi - NULL on output

cgi_init - - Initialize ClearSilver CGI environment

NEOERR *cgi_init (CGI **cgi, HDF *hdf);

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
Output:	cgi - an allocated CGI struct, including

cgi_redirect_uri - - send an HTTP 302 redirect response

void cgi_redirect_uri (CGI *cgi, char *fmt, ...);

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

Arguments:	cgi - cgi struct fmt - printf style format with args
Output:	None

cgi_output - - display the CGI output to the user

NEOERR *cgi_output (CGI *cgi, STRING *output);

Normally, this is called by cgi_display, but some
people wanted it external so they could call it
directly. None

Arguments:	cgi - a pointer a CGI struct allocated with cgi_init output - the data to send to output from the CGI
Output:	None

cgi_cookie_clear - - clear browser cookie

NEOERR *cgi_cookie_clear (CGI *cgi, char *name, char *domain, char *path);

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
Output:	None

cgi_redirect - - send an HTTP 302 redirect response

void cgi_redirect (CGI *cgi, char *fmt, ...);

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

Arguments:	cgi - cgi struct fmt - printf style format with args
Output:	None

cgi_url_unescape - - unescape an url encoded string

unsigned char *cgi_url_unescape (unsigned char *buf);

cgi_url_unescape will do URL unescaping on the passed in
string. This function modifies the string in place
This function will decode any %XX character, and will
decode + as space

Arguments:

buf - a 0 terminated string

cgi_vredirect - - send an HTTP 302 redirect response

void cgi_vredirect (CGI *cgi, int uri, char *fmt, va_list ap);

cgi_vredirect is mostly used internally, but can be used
if you need a varargs version of the function. None

Arguments:	cgi - cgi struct uri - whether the URL is full (1) or path only (0) fmt - printf format string ap - stdarg va_list
Output:	None

cgi_cs_init - - initialize CS parser with the CGI defaults

NEOERR *cgi_cs_init(CGI *cgi, CSPARSE **cs);

cgi_cs_init initializes a CS parser with the CGI HDF
context, and registers the standard CGI filters cs - the allocated/initialized CS struct

Arguments:	cgi - a pointer a CGI struct allocated with cgi_init cs - a pointer to a CS struct pointer
Output:	cs - the allocated/initialized CS struct

cgi_display - - render and display the CGI output to the user

NEOERR *cgi_display (CGI *cgi, char *cs_file);

cgi_display will render the CS template pointed to by
cs_file using the CGI's HDF data set, and send the
output to the user. Note that the output is actually
rendered into memory first. None

Arguments:	cgi - a pointer a CGI struct allocated with cgi_init cs_file - a ClearSilver template file
Output:	None

cgi_error - - display an error string to the user

void cgi_error (CGI *cgi, char *fmt, ...);

cgi_error will output a 500 error containing the
specified error message. This function is likely to be
removed from future versions in favor of a user error
mechanism. None

Arguments:	cgi - a pointer to a CGI struct fmt - printf style format string and arguments
Output:	None

cgi_cookie_set - - Set a browser Cookie

NEOERR *cgi_cookie_set (CGI *cgi, char *name, char *value, char *path, 

  char *domain, char *time_str, int persistent);

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

Output:

None

cgi_url_escape_more - - url escape a string

NEOERR *cgi_url_escape_more (unsigned char *buf, unsigned char **esc, unsigned char *other);

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
Output:	esc - a newly allocated string

cgi_neo_error - - display a NEOERR call backtrace

void cgi_neo_error (CGI *cgi, NEOERR *err);

cgi_neo_error will output a 500 error containing the
NEOERR call backtrace. This function is likely to be
removed from future versions in favor of some sort of
user error mechanism. None

Arguments:	cgi - a pointer to a CGI struct err - a NEOERR (see util/neo_err.h for details)
Output:	None

cgi_cookie_authority - - determine the cookie authority for a domain

char *cgi_cookie_authority (CGI *cgi, char *host);

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.
Output:	None

cgiwrap_writevf - - a wrapper for vprintf

NEOERR *cgiwrap_writevf (char *fmt, va_list ap);

cgiwrap_writevf is the formatted output command that
replaces vprintf or fvprintf(stdout) in a standard CGI
It is also used by cgiwrap_writef (the actual wrapped
function is a v type function) None

Arguments:	fmt - standard printf fmt string ap - stdarg argument pointer
Output:	None

Related Functions
cgiwrap_writevf, cgiwrap_write, cgiwrap_read, cgiwrap_iterenv, cgiwrap_putenv, cgiwrap_init_emu, cgiwrap_getenv, cgiwrap_init_std, cgiwrap_writef,

cgiwrap_write - - wrapper for the fwrite(stdout)

NEOERR *cgiwrap_write (char *buf, int buf_len);

cgiwrap_write is the block data output function for
cgiwrap that replaces fwrite(stdout) in regular CGIs None

Arguments:	buf - a character buffer buf_len - the length of the buffer in buf
Output:	None

Related Functions
cgiwrap_writevf, cgiwrap_write, cgiwrap_read, cgiwrap_iterenv, cgiwrap_putenv, cgiwrap_init_emu, cgiwrap_getenv, cgiwrap_init_std, cgiwrap_writef,

cgiwrap_read - - cgiwrap input function

void cgiwrap_read (char *buf, int buf_len, int *read_len);

cgiwrap_read is used to read incoming data from the
client, usually from a POST or PUT HTTP request. It
wraps the part of fread(stdin). read_len - the number of bytes read into buf

Arguments:	buf - a pre-allocated buffer to read the data into buf_len - the size of the pre-allocated buffer
Output:	read_len - the number of bytes read into buf

Related Functions
cgiwrap_writevf, cgiwrap_write, cgiwrap_read, cgiwrap_iterenv, cgiwrap_putenv, cgiwrap_init_emu, cgiwrap_getenv, cgiwrap_init_std, cgiwrap_writef,

cgiwrap_iterenv - - iterater for env vars

NEOERR *cgiwrap_iterenv (int n, char **k, char **v);

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

Related Functions
cgiwrap_writevf, cgiwrap_write, cgiwrap_read, cgiwrap_iterenv, cgiwrap_putenv, cgiwrap_init_emu, cgiwrap_getenv, cgiwrap_init_std, cgiwrap_writef,

cgiwrap_putenv - - wrap the putenv call

NEOERR *cgiwrap_putenv (char *k, char *v);

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

Arguments:	k - the env var name v - the new value for env var k
Output:	None

Related Functions
cgiwrap_writevf, cgiwrap_write, cgiwrap_read, cgiwrap_iterenv, cgiwrap_putenv, cgiwrap_init_emu, cgiwrap_getenv, cgiwrap_init_std, cgiwrap_writef,

cgiwrap_init_emu - - initialize cgiwrap for emulated use

void cgiwrap_init_emu (void *data, READ_FUNC read_cb, 

  WRITEF_FUNC writef_cb, WRITE_FUNC write_cb, GETENV_FUNC getenv_cb,

  PUTENV_FUNC putenv_cb, ITERENV_FUNC iterenv_cb);

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

Arguments:	data - user data to be passed to the specified callbacks read_cb - a cb to replace fread(stdin) writef_cb - a cb to repalce fprintf(stdout) write_cb - a cb to replace fwrite(stdout) getenv_cb - a cb to replace getenv putenv_cb - a cb to replace putenv iterenv_cb - a cb to replace the default environment iteration function (which just wraps walking the envp array)
Output:	None

Related Functions
cgiwrap_writevf, cgiwrap_write, cgiwrap_read, cgiwrap_iterenv, cgiwrap_putenv, cgiwrap_init_emu, cgiwrap_getenv, cgiwrap_init_std, cgiwrap_writef,

cgiwrap_getenv - - the wrapper for getenv

NEOERR *cgiwrap_getenv (char *k, char **v);

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.

Related Functions
cgiwrap_writevf, cgiwrap_write, cgiwrap_read, cgiwrap_iterenv, cgiwrap_putenv, cgiwrap_init_emu, cgiwrap_getenv, cgiwrap_init_std, cgiwrap_writef,

cgiwrap_init_std - - Initialize cgiwrap with default functions

void cgiwrap_init_std (int argc, char **argv, char **envp);

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

Arguments:	the arguments to main, namely argc/argv/envp
Output:	None

Related Functions
cgiwrap_writevf, cgiwrap_write, cgiwrap_read, cgiwrap_iterenv, cgiwrap_putenv, cgiwrap_init_emu, cgiwrap_getenv, cgiwrap_init_std, cgiwrap_writef,

cgiwrap_writef - - a wrapper for printf

NEOERR *cgiwrap_writef (char *fmt, ...);

cgiwrap_writef is the formatted output command that
replaces printf or fprintf(stdout) in a standard CGI None

Arguments:	fmt - standard printf fmt string and args
Output:	None

Related Functions
cgiwrap_writevf, cgiwrap_write, cgiwrap_read, cgiwrap_iterenv, cgiwrap_putenv, cgiwrap_init_emu, cgiwrap_getenv, cgiwrap_init_std, cgiwrap_writef,

cs_dump - - dump the cs parse tree

NEOERR *cs_dump (CSPARSE *parse, void *ctx, CSOUTFUNC cb);

cs_dump will dump the CS parse tree in the parse struct.
This can be useful for debugging your templates.
This function also uses the CSOUTFUNC callback to
display the parse tree. None

Arguments:	parse - the CSPARSE structure created with cs_init ctx - user data to be passed to the CSOUTFUNC cb - a CSOUTFUNC callback
Output:	None

Related Functions
cs_dump, cs_destroy, cs_render, cs_parse_string, cs_init, cs_parse_file, =, cs_register_strfunc,

cs_destroy - - clean up and dealloc a parse tree

void cs_destroy (CSPARSE **parse);

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

Arguments:	parse - a pointer to a parse structure.
Output:	parse - will be NULL

Related Functions
cs_dump, cs_destroy, cs_render, cs_parse_string, cs_init, cs_parse_file, =, cs_register_strfunc,

cs_render - - render a CS parse tree

NEOERR *cs_render (CSPARSE *parse, void *ctx, CSOUTFUNC cb);

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 *);
Output:	None

Related Functions
cs_dump, cs_destroy, cs_render, cs_parse_string, cs_init, cs_parse_file, =, cs_register_strfunc,

cs_parse_string - - parse a CS template string

NEOERR *cs_parse_string (CSPARSE *parse, char *buf, size_t blen);

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
Output:	None

Related Functions
cs_dump, cs_destroy, cs_render, cs_parse_string, cs_init, cs_parse_file, =, cs_register_strfunc,

cs_init - - create and initialize a CS context

NEOERR *cs_init (CSPARSE **parse, HDF *hdf);

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()

Related Functions
cs_dump, cs_destroy, cs_render, cs_parse_string, cs_init, cs_parse_file, =, cs_register_strfunc,

cs_parse_file - - parse a CS template file

NEOERR *cs_parse_file (CSPARSE *parse, char *path);

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
Output:	None

Related Functions
cs_dump, cs_destroy, cs_render, cs_parse_string, cs_init, cs_parse_file, =, cs_register_strfunc,

cs_register_strfunc - - register a string handling function

NEOERR *cs_register_strfunc(CSPARSE *parse, char *funcname, CSSTRFUNC str_func);

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

Related Functions
cs_dump, cs_destroy, cs_render, cs_parse_string, cs_init, cs_parse_file, =, cs_register_strfunc,

dictReleaseLock - - release lock on value.

void dictReleaseLock(dictCtx dict, void *lock);

Releases the lock on the value associated with <lock>. Once
the lock is released, the dictCleanupFunc callback can
be called for the value (see dictCleanup()). None.

Arguments:	dict - dictionary containing value to release. lock - lock to release.
Output:	None.

Related Functions
dictReleaseLock, dictRemove, dictNext, dictDestroy, dictCreate, dictSetValue, dictModifyValue, dictSearch, dictCleanup,

dictRemove - - remove item from dictionary.

BOOL dictRemove(dictCtx dict, char *id);

Removes item identified by <id> from <dict>. None.

Arguments:	dict - dictionary to search in. id - identifier of item to remove.
Output:	None.

Related Functions
dictReleaseLock, dictRemove, dictNext, dictDestroy, dictCreate, dictSetValue, dictModifyValue, dictSearch, dictCleanup,

dictNext - - search for next value in dictionary.

void *dictNext(dictCtx dict, char **id, void **plock);

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).
Output:	plock - set to value lock. id - pointer to id of found value

Related Functions
dictReleaseLock, dictRemove, dictNext, dictDestroy, dictCreate, dictSetValue, dictModifyValue, dictSearch, dictCleanup,

dictDestroy - - destroy dictionary.

void dictDestroy(dictCtx dict);

Release all resources used by <dict>. None.

Arguments:	dict - dictionary to destroy
Output:	None.

Related Functions
dictReleaseLock, dictRemove, dictNext, dictDestroy, dictCreate, dictSetValue, dictModifyValue, dictSearch, dictCleanup,

dictCreate - - create new dictionary.

NEOERR *dictCreate(dictCtx *dict, BOOL threaded, UINT32 root, UINT32 maxLevel, 

  UINT32 flushLimit, BOOL useCase, 

  dictFreeValueFunc freeValue, void *freeRock);

Returns a dictionary. If <threaded> is true, list is
multi-thread safe. <root>, <maxLevel>, and <flushLimit>
act as for skipNewList() (see skiplist.h) None.

Arguments:	threaded - true if list should be thread-safe. root - performance parameter (see above). maxLevel - performance parameter (see above). flushLimit - max deleted items to keep cached before forcing a flush. useCase - true to be case sensitive in identifiers freeValue - callback when freeing a value freeRock - context for freeValue callback
Output:	None.

Related Functions
dictReleaseLock, dictRemove, dictNext, dictDestroy, dictCreate, dictSetValue, dictModifyValue, dictSearch, dictCleanup,

dictSetValue - - set/reset an items value.

NEOERR *dictSetValue(dictCtx dict, char *id, void *value);

Updates the <id>/<value> pair into <dict>.
If <id> is not in <dict>, it is created. None.

Arguments:	dict - dictionary to add pair to. id - identifier to insert/update value - value to store (may NOT be NULL)
Output:	None.

Related Functions
dictReleaseLock, dictRemove, dictNext, dictDestroy, dictCreate, dictSetValue, dictModifyValue, dictSearch, dictCleanup,

dictModifyValue - - create/modify an item.

NEOERR *dictModifyValue(dictCtx dict, char *id, dictNewValueCB new_cb, 

  dictUpdateValueCB update, void *rock);

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>.
Output:	None.

Related Functions
dictReleaseLock, dictRemove, dictNext, dictDestroy, dictCreate, dictSetValue, dictModifyValue, dictSearch, dictCleanup,

dictSearch - - search for value in dictionary.

void *dictSearch(dictCtx dict, char *id, void **plock);

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.

Arguments:	dict - dictionary to search in. id - identifier of item to find. plock - place for value lock (or NULL).
Output:	plock - set to value lock.

Related Functions
dictReleaseLock, dictRemove, dictNext, dictDestroy, dictCreate, dictSetValue, dictModifyValue, dictSearch, dictCleanup,

dictCleanup - - cleanup dictionary

void dictCleanup(dictCtx dict, dictCleanupFunc cleanup, void *rock);

Calls <cleanup> for every item in <dict>. If <cleanup>
returns true, then item is removed from <dict>. None.

Arguments:	dict - dictionary to cleanup cleanup - cleanup callback rock - to pass to <cleanup>
Output:	None.

Related Functions
dictReleaseLock, dictRemove, dictNext, dictDestroy, dictCreate, dictSetValue, dictModifyValue, dictSearch, dictCleanup,

filter_wait - - wrap waitpid to decode the exitcode and why your filter quit

NEOERR *filter_wait(pid_t pid, int options, int *exitcode);

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))
Output:	exitcode -> the exitcode if the process existed normally

Related Functions
filter_wait, filter_create_fp, filter_create_fd,

filter_create_fp - - similar to filter_create_fd except with buffered FILE*

NEOERR *filter_create_fp(char *cmd, FILE **in, FILE **out, FILE **err, pid_t *pid);

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 err -> 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

Related Functions
filter_wait, filter_create_fp, filter_create_fd,

filter_create_fd - - Create a sub process and return the requested pipes

NEOERR *filter_create_fd(char *cmd, int *fdin, int *fdout, int *fderr, pid_t *pid);

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

Related Functions
filter_wait, filter_create_fp, filter_create_fd,

nerr_pass -

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.

Arguments:

with the macro, the function name, file and lineno are
automagically recorded. Just pass the error.

nerr_log_error -

void nerr_log_error (NEOERR *err);

currently, this prints out the error to stderr, and
free's the error chain

nerr_pass_ctx -

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.

nerr_ignore -

void nerr_ignore (NEOERR **err);

you should only call this if you actually handle the
error (should I rename it?). Free's the error chain.

nerr_raise -

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 - - Set part of the tree to link to another

NEOERR *hdf_set_symlink (HDF *hdf, char *src, char *dest);

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)
Output:	None

hdf_get_valuef - - Return the value of a node in the data set

char* hdf_get_valuef (HDF *hdf, char *namefmt, ...);

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

Arguments:	hdf -> the dataset node to start from namefmt -> the printf-style format string ... -> arguments to fill out namefmt
Output:	None

hdf_read_string - - read an HDF string Description: Input: Output:

NEOERR* hdf_read_string (HDF *hdf, char *s);

hdf_obj_value - - Return the value of a node

char* hdf_obj_value (HDF *hdf);

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

Arguments:	hdf -> the hdf dataset node
Output:	None

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, 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

Arguments:	hdf -> the dataset node to start from name -> the name to walk to
Output:	ret -> the dataset node you asked for

hdf_sort_obj - - sort the children of an HDF node

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)

Arguments:	h - HDF node compareFunc - function which returns 1,0,-1 depending on some criteria. The arguments to this sort function are pointers to pointers to HDF elements. For example: int sortByName(const void a, const void b) { HDF ha = (HDF )a; HDF hb = (HDF )b; * return strcasecmp(hdf_obj_name(ha), hdf_obj_name(hb)); } *
Output:	None (h children will be sorted)

hdf_write_file_atomic - - write an HDF data file atomically

NEOERR* hdf_write_file_atomic (HDF *hdf, char *path);

hdf_write_file_atomic is similar to hdf_write_file,
except the new file is created with a unique name and
then rename(2) is used to atomically replace the old
file with the new file
Input:
Output: