Appendix A   Server Plug-in API Function Definitions

This chapter lists all the public functions and macros of the Server plug-in Applications Programming Interface (server plug-in API) in alphabetical order. Each description identifies the name of the function, its header file, its syntax, its parameters, an example of its use, and a list of related functions. Descriptions of the data structures that are not common to the C programming environment can be found in Appendix B "Server Data Structures."

cache_digest (declared in libproxy/cache.h)

The cache_digest function calculates the MD5 signature of a specified URL and stores the signature in a digest variable.

Syntax

#include <libproxy/cache.h>
void cache_digest(char *url, unsigned char digest[16]));

Returns

void

Parameters

char *url is a string containing the cache filename of a URL.

name *digest is an array to receive first 48 bits of the signature of the URL.

See also

cache_fn_to_dig

cache_filename (declared in libproxy/cutil.h)

The cache_filename function returns the cache filename for a given URL, specified by MD5 signature.

Syntax

#include <libproxy/cutil.h>
char *cache_filename(unsigned char digest[16]);

Returns

A new string containing the cache filename.

Parameters

char *digest is an array containing the MD5 signature of a URL.

See also

cache_fn_to_dig

cache_fn_to_dig (declared in libproxy/cutil.h)

The cache_fn_to_dig function converts a cache filename of a URL into a partial MD5 digest.

Syntax

#include <libproxy/cutil.h>
void *cache_fn_to_dig(char *name, unsigned char digest[16]));

Returns

void

Parameters

char *name is a string containing the cache filename of a URL.

name *digest is an array to receive first 48 bits of the signature of the URL.

ce_free (declared in libproxy/cache.h)

The ce_free function releases memory allocated by the ce_lookup function.

Syntax

#include <libproxy/cache.h>
void cd_free(CacheEntry *ce);

Returns

void

Parameters

CacheEntry *ce is a cache entry structure to be destroyed.

See also

ce_lookup

ce_lookup (declared in libproxy/cache.h)

The ce_lookup cache entry lookup function looks up a cache entry for a specified URL.

Syntax

#include <libproxy/cache.h>
CacheEntry *ce_lookup(Session *sn, Request *rq, char *url, time_t ims_c);

Returns

• NULL if caching is not enabled
• A newly allocated CacheEntry structure, whether or not a copy existed in the cache. Within that structure, the ce->state field reports about the existence:

CACHE_NO signals that the document is not and will not be cached; other fields in the cache structure may be NULL

CACHE_CREATE signals that the cache file doesn't exist but may be created once the remote server is contacted. However, during the retrieval it may turn out that the document is not cacheable.

CACHE_REFRESH signals that the cache file exists, but it needs to be refreshed (an up-to-date check must be made) before it's used; note that the data may still be up-to-date, but the remote server needs to be contacted to find that out. If not, the cache file will be replaced with the new document version sent by the remote origin server.

CACHE_RETURN_FROM_CACHE signals that the cache file exists and is up-to-date based on the configuration and current parameters controlling what is considered fresh.

CACHE_RETURN_ERROR is a signal that happens only if the proxy is set to no-network mode (connect-Modenese), and the document does not exist in the cache.

Parameters

Session *sn identifies the Session structure.

Request *rq identifies the Request structure.

char *url contains the name of the URL for which the cache is being sought.

time-out misc. is the if-modified-since time.

See also

ce_free

cif_load (declared in libproxy/cif.h)

The cif_load function reads the directory-wide cache information file and stores the data in nodes about files.

Syntax

#include <libproxy/cif.h>
int cif_load(CacheEntry *arr, int start, int stop);

Returns

• nonzero if the write was successful
• 0 if the write was unsuccessful

Parameters

CacheEntry *ce is a cache entry structure to be written to the .cif file.

See also

cif_read_entry

cif_clear (declared in libproxy/cif.h)

The cif_clear function clears the CacheEntry block array so that it can be reused. This function does not write the data back into the cache information file.

Syntax

#include <libproxy/cif.h>
void cif_clear(CacheEntry *arr, int size);

Returns

void

Parameters

CacheEntry *arr is a cache entry array.

int size is the number of items in the array.

See also

cif_load_all_data, cif_load_cif

cif_load_all_data (declared in libproxy/cif.h)

The cif_load_all_data function loads the cache information file (CIF) entries from the CIF and then invokes the stat function for each file referred to by the CIF entries.

Syntax

#include <libproxy/cif.h>
int cif_laod_all_data (char *cif_fn, CacheEntry *arr, int max_entries);

Returns

The actual number of entries loaded into the array.

Parameters

char *cif_fn is the absolute pathname for the CIF.

CacheEntry *arr is an array of empty CacheEntry items to be loaded by this function.

int max_entries is the maximum number of elements that the array can accept.

See also

cif_clear, cif_load_cif

cif_load_cif (declared in libproxy/cif.h)

The cif_load_cif function loads an entire cache information file (CIF) into a specified empty array.

Syntax

#include <libproxy/cif.h>
int cif_laod_cif(char *cif_fn, CacheEntry *arr, int max_entries);

Returns

The actual number of entries loaded into the array.

Parameters

char *cif_fn is the absolute pathname for the CIF.

CacheEntry *arr is a cache entry array.

int max_entries is the maximum number of elements in the array.

See also

cif_clear

cif_read_entry (declared in libproxy/cif.h)

The cif_read_entry function reads the cache information file entry for a specified cache entry. There is rarely any need to use this function directly, because the ce_lookup function calls it.

Syntax

#include <libproxy/cif.h>
int cif_read_entry(CacheEntry *ce);

Returns

• 1 if the read was successful
• 0 if the read was unsuccessful

Parameters

CacheEntry *ce is a cache entry structure to be read from the cache information file.

See also

cif_write_entry

cif_stat_entries (declared in libproxy/cif.h)

The cif_stat_entries function gathers information from the file system into the entries of a specified CacheEntry array. For each entry, it sets the removed member in the CacheEntry if the file no longer exists; otherwise it uses the stat function to establish the values for creation time, last access time, size in bytes, and size in blocks and stores these values in the finfo element of the array entry.

Syntax

#include <libproxy/cif.h>
int cif_stat_entries(CacheEntry *arr, int cnt);

Returns

the number of files that it examined with the stat function (cnt minus the number of files that were removed).

Parameters

CacheEntry *arr is an existing CacheEntry array.

int cnt is the number of entries to obtain.

See also

cif_read_entry

cif_write_entry (declared in libproxy/cif.h)

The cif_write_entry function writes a CIF entry for a specified CacheEntry structure. The CIF entry is stored in the .cif file in the directory in which the cache file is located. Entries are appended to the CIF, so it can contain multiple cache entries, but the last one is the most current, and is the only one that you should use. The Cache Manager periodically rewrites the cache information files, removing old entries.

Syntax

#include <libproxy/cif.h>
int cif_write_entry(CacheEntry *ce);

Returns

• nonzero if the write was successful
• 0 if the write was unsuccessful

Parameters

CacheEntry *ce is a cache entry structure to be written to the .cif file.

See also

cif_read_entry

cinfo_find (declared in base/cinfo.h)

The cinfo_find function finds the content information for the URI and returns a pointer to a structure containing the information. Use this function to retrieve information on a URI or a local filename in order to tell the client the type of file it will be receiving from the server.

Syntax

#include </base/cinfo.h>
cinfo *cinfo_find(char *uri);

Returns

• The pointer to a newly allocated cinfo structure if content was found
• NULL if no content was found

The cinfo structure that is allocated and returned contains information on the type of data in a file, if and how the data is encoded, and if the data is a textual document; it also contains information on the language of the text. The pointers contained in the returned cinfo structure point to data in the types database. It is important to note that you should not deallocate these pointers. You can change the data in your cinfo structure by first making a copy of the data to which the original structure elements points. However, you must deallocate your cinfo structure when you are done using it.

The cinfo find function can also be used with local filenames. Simply pass the local filename instead of the URI.

Parameters

char *uri is the name of a URI. The filename specified by uri must be the string following the last backslash (/) in the URI. In addition, multiple filename extensions should be separated by CINFO_SEPARATOR (currently defined as a period).

condvar_init (declared in base/crit.h)

The condvar_init function is a critical-section function that initializes and returns a new condition variable associated with a specified critical-section variable. You can use the condition variable to manage the prevention of interference between two threads of execution.

Syntax

#include <base/crit.h>
CONDVAR condvar_init(CRITICAL id);

Returns

A newly allocated condition variable (CONDVAR).

Parameters

CRITICAL id is a critical-section variable.

See also

condvar_notify, condvar_terminate, condvar_wait, crit_init.

condvar_notify (declared in base/crit.h)

The condvar_notify function is a critical-section function that awakens any threads that are blocked on the given critical-section variable. Use this function to awaken threads of execution of a given critical section. First, use crit_enter to gain ownership of the critical section. Then use the returned critical-section variable to call condvar_notify to awaken the threads. Finally, when condvar_notify returns, call crit_exit to surrender ownership of the critical section.

Syntax

#include <base/crit.h>
void condvar_notify(CONDVAR cv);

Returns

void

Parameters

CONDVAR cv is a condition variable.

See also

condvar_init, condvar_terminate, condvar_wait, crit_enter, crit_exit, crit_init.

condvar_terminate (declared in base/crit.h)

Critical-section function that frees a condition variable. Use this function to free a previously allocated condition variable.

---

Caution

Terminating a condition variable that is in use can lead to unpredictable results.

---

Syntax

#include <base/crit.h>
void condvar_terminate(CONDVAR cv);

Returns

void

Parameters

CONDVAR cv is a condition variable.

See also

condvar_init, condvar_notify, condvar_wait, crit_init.

condvar_wait (declared in base/crit.h)

Critical-section function that blocks on a given condition variable. Use this function to wait for a critical section (specified by a condition variable argument) to become available. The calling thread is blocked until another thread calls condvar_notify with the same condition variable argument. The caller must have entered the critical section associated with this condition variable before calling condvar_wait.

Syntax

#include <base/crit.h>
void condvar_wait(CONDVAR cv);

Parameters

CONDVAR cv is a condition variable.

Returns

void

See also

condvar_init, condvar_notify, condvar_terminate, crit_init.

crit_enter (declared in base/crit.h)

Critical-section function that attempts to enter a critical section. Use this function to gain ownership of a critical section. If another thread already owns the section, the calling thread is blocked until the first thread surrenders ownership by calling crit_exit.

Syntax

#include <base/crit.h>
void crit_enter(CRITICAL crvar);

Returns

void

Parameters

CRITICAL

daemon_atrestart (declared in netsite.h)

The daemon_atrestart function lets you register a callback function named by fn to be used when the server receives a restart signal. Use this function when you need a callback function to deallocate resources allocated by an initialization function. The daemon_atrestart function is a generalization of the magnus_atrestart function.

Syntax

#include <netsite.h>
void daemon_atrestart(void (*fn)(void *), void *data);

Returns

void

Parameters

void (* fn) (void *) is the callback function.

void *data is the parameter passed to the callback function when the server is restarted.

Example

/* Close log file when server is restarted */
daemon_atrestart(brief_terminate, NULL);
return REQPROCEED;

See also

http_start_response.

fast_dump_cif (declared in libproxy/cif.h)

The fast_dump_cif function dumps all CIF entries from a string array into an existing CIF file.

Syntax

#include <libproxy/cif.h>
int fast_dump_cif(char *cif_fn, char **arr, int cnt);

Returns

The number of entries dumped into the array (cnt minus any NULLs).

Parameters

char *cif_fn is the absolute pathname for the CIF.

char **arr is a string array containing all the entries. Each must include a trailing /n character, or the file will become corrupted.

int cnt is the number of entries in the array. If any entry is NULL, the function ignores the cnt value.

See also

cif_write_entry

fast_get_cif_entry_for (declared in libproxy/cif.h)

The fast_get_cif_entry_for function gets the CIF entry for a specific cache file. It accepts the entry as a single string, without parsing it.

Syntax

#include <libproxy/cif.h>
char *fast_get_cif_entry_for(char *cif_fn, char *name);

Returns

A string containing the CIF entry.

Parameters

char *cif_fn is the absolute pathname for the CIF.

char *name is the relative name of the cache file (relative to the directory containing the CIF).

See also

cif_read_entry

fast_load_cif (declared in libproxy/cif.h)

The fast_load_cif function loads all CIF entries as unparsed strings into an array.

Syntax

#include <libproxy/cif.h>
int fast_load_cif(char *cif_fn, char **arr, int max, int *multiples_ret);

Returns

• the number of entries loaded into the array if the operation was successful
• 0 if the operation was unsuccessful

Parameters

char *cif_fn is the absolute pathname for the CIF.

char **arr is a string array where the function will place the entries. Each will include a trailing /n character.

int max is the maximum number of entries the array can receive.

int *multiples_ret is an integer to receive the number of multiple entries encountered.

See also

cif_write_entry

fast_put_cif_entry (declared in libproxy/cif.h)

The fast_put_cif_entry function writes a properly formatted CIF entry to the specified CIF.

Syntax

#include <libproxy/cif.h>
int fast_put_cif_entry(char *cif_fn, char *entry);

Returns

• nonzero if the write was successful
• 0 if the write was unsuccessful

Parameters

char *cif_fn is the absolute pathname for the CIF.

char *entry is the formatted CIF entry, including the trailing \n character.

See also

cif_write_entry

filebuf_buf2sd (declared in base/buffer.h)

The filebuf_buf2sd function sends a file buffer to a socket and returns the number of bytes sent.

Use this function to send the contents of a file to a server.

Syntax

#include <base/buffer.h>
int filebuf_buf2sd(filebuf *buf, SYS_NETFD sd);

Returns

• The number of bytes sent to the socket, if successful
• The constant IO_ERROR if the file buffer could not be sent

Parameters

filebuf *buf is the name of the file buffer.

SYS_NETFD sd is the platform-independent identifier of the socket.

Example

if(filebuf_buf2sd(buf, sn->csd) == IO_ERROR)
   ret = REQ_EXIT;
filebuf_close(buf);

See also

filebuf_close, filebuf_open, netbuf_buf2sd

filebuf_close (declared in base/buffer.h)

The filebuf_close function deallocates a file buffer and closes its associated files.

Generally, use filebuf_open to first open a file buffer and then use filebuf_getc to access the information in the file. After you have finished using the file buffer, use filebuf_close to close it.

Syntax

#include <base/buffer.h>
void filebuf_close(filebuf *buf);

Returns

void

Parameters

filebuf *buf is the name of the file buffer.

Example

if(filebuf_buf2sd(buf, sn->csd) == IO_ERROR)
   ret = REQ_EXIT;
filebuf_close(buf);

See also

filebuf_buf2sd, filebuf_getc, filebuf_open, netbuf_close

filebuf_getc (declared in base/buffer.h)

The filebuf_getc function retrieves a character from the current cursor position and returns an integer.

Use filebuf_getc to sequentially read one character from the file buffer.

Syntax

#include <base/buffer.h>
netbuf_getc(netbuf b);

Returns

• An integer representation of the character retrieved
• The constant IO_EOF or IO_ERROR upon an end of file or error

Parameters

netbuf b is the name of the file buffer.

See also

filebuf_close, netbuf_getc, netbuf_open

filebuf_open (declared in base/buffer.h)

The filebuf_open function opens a new file buffer and returns a pointer to the buffer. Use this function to read through a file using a buffer. This function provides more efficient file access because using the function guarantees use of buffered file I/O in environments where it is not supported by the operating system.

Syntax

#include <base/buffer.h>
filebuf *filebuf_open(SYS_FILE fd, int sz);

Returns

• A pointer to a new buffer structure to hold the data, if one was created
• NULL if no buffer could be opened

Parameters

SYS_FILE fd is the platform-independent file descriptor.

int sz is the size, in characters, to be used for the buffer.

Example

buf = filebuf_open(fd, &finfo);
if (!buf){
   system_fclose(fd);
   goto done;
}

See also

filebuf_close, filebuf_open_nostat, netbuf_open

filebuf_open_nostat (declared in base/buffer.h)

The filebuf_open_nostat function opens a new file buffer and returns a new buffer structure. This function accomplishes the same purpose as the filebuf_open function but is more efficient because it does not need to call the stat function.

Syntax

#include <base/buffer.h>
#include <sys/stat.h>
filebuf* filebuf_open_nostat(SYS_FILE fd, int sz, struct stat *finfo);

Returns

• A pointer to a new buffer structure to hold the data, if one was created
• NULL if no buffer could be opened

Parameters

SYS_FILE fd is the platform-independent file descriptor.

int sz is the file descriptor to be opened.

struct stat *finfo is the file descriptor to be opened. Before calling the filebuf_open_nostat function, you must call the stat function for the file, so that the parameter returned by the stat function (specified by finfo) has been established.

Example

buf = filebuf_open_nostat(fd, FILE_BUFFERSIZE, &finfo);
if (!buf){
   system_fclose(fd);
   goto done;
}

See also

filebuf_close, filebuf_open

FREE (declared in netsite.h)

The FREE macro is a platform-independent substitute for the C library routine free. It deallocates the space previously allocated by MALLOC or STRDUP to a specified pointer.

Syntax

#include <netsite.h>
FREE(ptr);

Returns

void

Parameters

ptr is a (void) pointer to an object. If the pointer is not one created by MALLOC or STRDUP, the behavior is undefined.

Example

if(alt) {
   pb_param *pp = pblock_find("ppath", rq->vars);
   /* Trash the old value */
   FREE(pp->value);
   /* Dup it because the library will later free this pblock */
   pp->value = STRDUP(alt);
   return REQ_PROCEED;
}
/* Else do nothing */
return REQ_NOACTION;

See also

MALLOC, REALLOC, STRDUP

fs_blks_available (declared in libproxy/fs.h)

The fs_blks_available function returns the number of disk blocks available on the disk partition on which a specified directory resides.

Syntax

#include <libproxy/fs.h>
long fs_blks_avail(char *root);

Returns

The number of available disk blocks

Parameters

char *root is the name of the directory.

See also

fs_blk_size

fs_blk_size (declared in libproxy/fs.h)

The fs_blk_size function returns the block size of the disk partition on which a specified directory resides.

Syntax

#include <libproxy/fs.h>
long fs_blk_size(char *root);

Returns

the block size, in bytes

Parameters

char *root is the name of the directory.

See also

fs_blks_available

func_exec (declared in frame/func.h)

The func_exec function executes the function named by the fn entry in a specified parameter block, for a specified Session and a specified Request. If the function name is not found, the func_exec function creates a LOG_MISCONFIG message for the missing function parameter.

You can use this function to execute a server application function (SAF) by identifying it in the parameter block.

Syntax

#include <frame/func.h>
int func_exec(pblock *pb, Session *sn, Request *rq);

Returns

• The value returned by the executed function.
• The constant REQ_ABORTED if no function was executed

Parameters

pblock *pb is the parameter block containing the function.

Session *sn identifies the Session structure.

Request *rq identifies the Request structure.

The Session and Request parameters can be the same as the ones passed to your function.

See also

log_error

func_find (declared in frame/func.h)

The func_find function returns a pointer to the function specified by name. If no pointer exists, the function returns NULL.

Syntax

#include <frame/func.h>
FuncPtr func_find(char *name);

Returns

• A pointer to the chosen function, suitable for dereferencing.
• NULL if the function could not be found.

Parameters

char *name is the name of the function.

Example

/* this block of code does the same thing as func_exec */
   char *afunc = pblock_findval("afunction", pb);
   FuncPtr afnptr = func_find(afunc);
   if(afnptr) return (afnptr)(pb, sn, rq);

See also

func_exec

http_dump822 (declared in frame/http.h)

Utility function that prints headers into a buffer and returns it.

The http_dump822 function prints headers from the parameter block named by pb into a buffer named by t, with the size and position specified by tsz and pos, respectively.

Use this function to serialize the headers so that they can be sent, for example, in a mail message.

Syntax

#include <frame/http.h>
char *http_dump822(pblock *pb, char *t, int *pos, int tsz);

Returns

The buffer, reallocated if necessary, and modifies pos to denote a new position in the buffer.

See also

http_handle_session, http_scan_headers, http_start_response, protocol_status

http_hdrs2env (declared in frame/http.h)

Utility function that converts a parameter block entry into an enviroment.

The http_hdrs2env function takes the entries in the parameter block named by pb and converts them to an environment.

Note that each entry is converted to uppercase text with the prefix HTTP_.

A hyphen (-) or double hyphen (--) in the text is automatically converted into an underscore (_), or double underscore (_ _), respectively.

Use this function to create an environment that a program can later use.

Syntax

#include <frame/http.h>
char **http_hdrs2env(pblock *pb);

Returns

A pointer to the new environment.

See also

http_handle_session, http_scan_headers, http_start_response, protocol_status

# http_scan_headers (declared in frame/http.h)

Utility function that scans HTTP headers from a network buffer and places them in a parameter block.

Scans HTTP headers from the network buffer named by buf, and places them in the parameter block named by headers.

The Session structure named by sn contains a pointer to a netbuf called inbuf. If the parameter buf is NULL, the function automatically uses inbuf.

Folded lines are joined and the linefeeds are removed (but not the whitespace). If there are any repeat headers, they are joined and the two field bodies are separated by a comma and space. For example, multiple mail headers are combined into one header and a comma is used to separate the field bodies.

The parameter t defines a string of length REQ_MAX_LINE. This is an optimization for the internal code to reduce usage of runtime stack.

Note that sn is an optional parameter that is used for error logs. Use NULL if you wish.

Syntax

#include <frame/http.h>
int http_scan_headers(Session *sn, netbuf *buf, char *t, pblock *headers);

Returns

• The constant REQ_PROCEED if the operation succeeded
• The constant REQ_ABORTED if the operation did not succeed

See also

http_handle_session, http_start_response, protocol_status, protocol_scan_headers

http_set_finfo (declared in frame/http.h)

Utility function that retrieves HTTP information about a file being sent to a client.

The http_set_finfo function retrieves the length and date from the stat structure named by finfo, for the Session named by sn and the request denoted by rq.

Note that the stat structure contains the information about the file you are sending back to the client.

Use http_set_finfo only after receiving a start_response from a service class server application function (SAF).

Syntax

#include <frame/http.h>
int http_set_finfo(Session *sn, Request *rq, struct stat *finfo);

Returns

• The constant REQ_PROCEED if the request can proceed normally
• The constant REQ_ABORTED if the function should treat the request normally, but not send any output to the client

See also

http_handle_session, http_scan_headers, http_start_response, protocol_status, protocol_set_finfo

http_start_response (declared in frame/http.h)

Utility function that initiates the HTTP response.

The http_start_response function initiates the HTTP response for the Session named by sn and the request denoted by rq. If the protocol version is HTTP/0.9, the function does nothing. If the protocol version is HTTP/1.0, the function sends a header.

Note that if the return value is REQ_NOACTION, you should not send the data you were going to send in response to the request. Otherwise, http_start_response will return REQ_PROCEED.

Use this function to set up HTTP and prepare the server and the client to receive data.

Syntax

#include <frame/http.h>
int http_start_response(Session *sn, Request *rq);

Returns

• The constant REQ_PROCEED if the operation succeeded, in which case you can send the data you were preparing to send
• The constant REQ_NOACTION if the operation succeeded, but the client has requested that the server not send the data because the client has it in cache.
• The constant REQ_ABORTED if the operation did not succeed.

See also

http_handle_session, http_scan_headers, protocol_status, protocol_start_response

http_status (declared in frame/http.h)

Utility function that sets session status and reason string.

The http_status function sets the session status to indicate whether an error condition occurred.

If the reason string is NULL, the server attempts to find a reason string for the given status code. If it finds none, it returns "Unknown reason."

Use this function to check the status of the Session before calling the function start_response.

The following is a list of valid status codes:

PROTOCOL_OK
PROTOCOL_NO_RESPONSE
PROTOCOL_REDIRECT
PROTOCOL_NOT_MODIFIED
PROTOCOL_BAD_REQUEST
PROTOCOL_UNAUTHORIZED
PROTOCOL_FORBIDDEN
PROTOCOL_NOT_FOUND
PROTOCOL_PROXY_UNAUTHORIZED
PROTOCOL_SERVER_ERROR
PROTOCOL_NOT_IMPLEMENTED

Syntax

#include <frame/http.h>
void http_status(Session *sn, Request *rq, int n, char *r);

Returns

void, but it sets values in the session/request designated by sn/rq for the status code and the reason string

See also

http_handle_session, http_scan_headers, http_start_response, protocol_status

http_uri2url (declared in frame/http.h)

Utility function that converts URI to URL.

The http_uri2url function takes the given URI prefix and suffix, and creates a newly-allocated full URL in the form http://(server):(port)(prefix)(suffix).

If you want to skip either the URI prefix or suffix, use NULL as the value for either parameter. To redirect the client somewhere else, use the function pblock_nvinsert to create a new entry in the vars in the pblock in your request structure.

Use http_uri2url when you want to convert from URI to URL in order to pass a fully qualified resource locator to a client.

Syntax

#include <frame/http.h>
char *http_uri2url(char *prefix, char *suffix);

Returns

A new string containing the URL

See also

http_handle_session, http_scan_headers, http_start_response, protocol_status, protocol_uri2url

log_error (declared in frame/log.h)

The log_error function creates an entry in an error log, recording the date, the severity, and a specified text.

Syntax

#include <frame/log.h>
int log_error(int degree, char *func, Session *sn, Request *rq, char *fmt, ...);

Returns

• 0 if the log entry was created.
• -1 if the log entry was not created.

Parameters

int degree specifies the severity of the error. It must be one of the following constants:

LOG_WARN — warning
LOG_MISCONFIG — a syntax error or permission violation
LOG_SECURITY—- an authentication failure or 403 error from a host
LOG_FAILURE — an internal problem
LOG_CATASTROPHE — a non-recoverable server error
LOG_INFORM — an informational message

char *func is the name of the function where the error occurred.

Session *sn identifies the Session structure.

Request *rq identifies the Request structure.

char *fmt specifies the format for the printf function that delivers the message.

... represents a sequence of parameters for the printf function.

Example

if(!groupbuf) {
   log_error(LOG_WARN, "send-file", sn, rq,
      "error opening buffer from %s (%s)"), path,
         system_errmsg(fd));;
   return REQ_ABORTED;
}

See also

func_exec

magnus_atrestart (declared in netsite.h)

---

Note	Use the daemon-atrestart function in place of the obsolete magnus_atrestart function.

---

The magnus_atrestart function lets you register a callback function named by fn to be used when the server receives a restart signal. Use this function when you need a callback function to deallocate resources allocated by an initialization function.

Syntax

#include <netsite.h>
void magnus_atrestart(void (*fn)(void *), void *data);

Returns

void

Parameters

void (* fn) (void *) is the callback function.

void *data is the parameter passed to the callback function when the server is restarted.

Example

/* Close log file when server is restarted */
magnus_atrestart(brief_terminate, NULL);
return REQPROCEED;

make_log_time (declared in libproxy/util.h)

The make_log_time function translates a given time from time_t format to a character format suitable for access logs. It can also deliver the current time in the access log format.

Syntax

#include <libproxy/util.h>
char *make_log_time(time_t tt);

Returns

• the character equivalent of the specified time tt, if tt is not 0
• the current local time, in character format if tt is 0

Parameters

time_t tt is a time.

MALLOC (declared in netsite.h)

The MALLOC macro is a platform-independent substitute for the C library routine malloc. It uses memory pools, creating one for each request, automatically freeing it after the request has been processed. The data in the Request parameter block is allocated by MALLOC, not PERM_MALLOC, which provides allocation that persists beyond the end of the request. If memory pooling has been disabled in the configuration file, PERM_MALLOC and MALLOC both obtain their memory from the system heap.

Syntax

#include <netsite.h>
MALLOC(size)

Returns

A pointer to space for an object of size size.

Parameters

size (an int) is the number of bytes to allocate.

Example

/* Initialize hosts array */
    num_hosts = 0;
    hosts = (char **) MALLOC(1 * sizeof(char *));
    hosts[0] = NULL;

See also

PERM_MALLOC, REALLOC, FREE, PERM_FREE, STRDUP, PERM_STRDUP

netbuf_buf2sd (declared in base/buffer.h)

The netbuf_buf2sd function sends a buffer to a socket. You can use this function to send data from IPC pipes to the client.

Syntax

#include <base/buffer.h>
int netbuf_buf2sd(netbuf *buf, SYSNETFD sd, int len);

Returns

• The number of bytes transferred to the socket, if successful
• The constant IO_ERROR if unsuccessful

Parameters

netbuf *buf is the buffer to send.

SYS_NETFD sd is the platform-independent socket identifier.

int len is the buffer length.

See also

filebuf_buf2sd, netbuf_close, netbuf_grab, netbuf_open

netbuf_close (declared in base/buffer.h)

The netbuf_close function deallocates a network buffer and closes its associated files. Use this function when you need to deallocate the network buffer and close the socket.

You should never close the netbuf parameter in a Session structure.

Syntax

#include <base/buffer.h>
void netbuf_close(netbuf *buf);

Returns

void

Parameters

netbuf *buf is the buffer to close.

See also

filebuf_close, netbuf_grab, netbuf_open

netbuf_getc (declared in base/buffer.h)

The netbuf_getc function retrieves a character from the cursor position of the network buffer specified by b.

Syntax

#include <base/buffer.h>
netbuf_getc(netbuf b);

Returns

• The integer representing the character, if one was retrieved
• The constant IO_EOF or IO_ERROR, for end of file or error

Parameters

netbuf b is the buffer from which to retrieve one character.

See also

filebuf_getc, netbuf_grab, netbuf_open

netbuf_grab (declared in base/buffer.h)

The netbuf_grab function assigns a size to the array in the network buffer named by buf. The size of the array is specified by sz, which is the number of bytes from the buffer's associated object.

The buffer processes the allocation and deallocation of the array.

This function is used by the function netbuf_buf2sd.

Syntax

#include <base/buffer.h>
int netbuf_grab(netbuf *buf, int sz);

Returns

• The number of bytes actually read (from 1through sz), if the assignment was successful
• The constant IO_EOF or IO_ERROR, for end of file or error

Parameters

netbuf *buf is the buffer into which to read.

int sz is the array size for the buffer to allocate.

See also

netbuf_close, netbuf_open

netbuf_open (declared in base/buffer.h)

The netbuf_open function opens a new network buffer and returns it. You can use netbuf_open to create a netbuf structure and start using buffered I/O on a socket.

Syntax

#include <base/buffer.h>
netbuf* netbuf_open(SYS_NETFD sd, int sz);

Returns

A new netbuf structure (network buffer)

Parameters

SYS_NETFD sd is the platform-independent socket identifier.

int sz is the number of characters to allocate for the network buffer.

See also

filebuf_open, netbuf_close, netbuf_grab

net_ip2host (base/net.h)

The net_ip2host function transforms a textual IP address into a fully qualified domain name and returns it.

Syntax

#include <base/net.h>
char *net_ip2host(char *ip, int verify);

Returns

• A new string containing the fully qualified domain name, if the transformation was accomplished.
• NULL if the transformation was not accomplished.

Parameters

char *ip is the IP address as a character string in dotted-decimal notation: nnn.nnn.nnn.nnn

int verify, if nonzero, specifies that the function should verify the fully qualified domain name. Though this requires an extra query, you should use it when determining access control.

See also

net_sendmail

net_read (declared in base/net.h)

The net_read function reads bytes from a specified socket into a specified buffer. The function waits to receive data from the socket until either at least one byte is available in the socket or the specified time has elapsed.

Syntax

#include <base/net.h
int net_read (SYS_NETFD sd, char *buf, int sz, int timeout);

Returns

• The number of bytes read, which will not exceed the maximum size, sz.
• A negative value if an error has occurred, in which case errno is set to the constant ETIMEDOUT if the operation did not complete before timeout seconds elapsed.

Parameters

SYS_NETFD sd is the platform-independent socket descriptor.

char *buf is the buffer to receive the bytes.

int sz is the maximum number of bytes to read.

int timeout is the number of seconds to allow for the read operation before returning. The purpose of timeout is not to return because not enough bytes were read in the given time but to limit the amount of time devoted to waiting until some data arrives.

See also

net_socket, net_write

net_socket (declared in base/net.h)

The net_socket function opens a connection to a socket, creating a new socket descriptor. The socket is not connected to anything, and is not listening to any port. A function must use net_connect to make a connection, and net_accept to listen.

Syntax

#include <base/net.h>
SYS_NETFD net_socket (int domain, int type, int protocol);

Returns

The platform-independent socket descriptor (SYS_NETFD) associated with the socket.

Parameters

int domain must be the constant AF_INET.

int type must be the constant SOCK_STREAM.

int protocol must be the constant IPPROTO_TCP.

See also

net_read, net_write

net_write (declared in base/net.h)

The net_write function writes a specified number of bytes to a specified socket into a specified buffer. It returns the number of bytes written.

Syntax

#include <base/net.h>
int net_write (SYS_NETFD sd, char *buf, int sz);

Returns

The number of bytes written, which may be less than the requested size if an error occurred.

Parameters

SYS_NETFD sd is the platform-independent socket descriptor.

char *buf is the buffer containing the bytes.

int sz is the number of bytes to write.

Example

/* Start response by giving boundary string */
if(net_write(sn->csd, FIRSTMSG, strlen(FIRSTMSG)) == IO_ERROR)
   return REQ_EXIT;

See also

net_socket

param_create (declared in base/pblock.h)

The param_create function creates a parameter block structure containing a specified name and value. If the name or value is not NULL, the pair is copied and placed into the new parameter block structure; otherwise the pair is created with name and value both. Use this function to prepare a parameter block structure to be used in calls to parameter block routines such as pblock_pinsert.

Syntax

#include <base/pblock.h>
pb_param *param_create(char *name, char *value);

Returns

A new parameter block structure.

Parameters

char *name is the string containing the name portion of the name-value pair.

char *value is the string containing the value portion of the name-value pair.

Example

pblock *pb = pblock_create(4);
pb_param *newpp = param_create("hello","world");
pblock_pinsert(newpp, pb);

See also

param_free

param_free (declared in base/pblock.h)

The param_free function frees the parameter specified by pp. Use the param_free function for error checking after removing the function using pblock_remove.

Syntax

#include <base/pblock.h>
int param_free(pb_param *pp);

Returns

• 1 if the parameter was freed
• 0 if the parameter was NULL

Parameters

pb_param *pp is the name portion of a name-value pair stored in a pblock.

Example

int check(pblock *pb)
{
    if(param_free(pblock_remove("hello", pb)))
      return 1; /* signal that we removed it */
   else
      return 0; /* We didn't remove it. */
}

See also

param_create, pblock_remove

pblock_copy (declared in base/pblock.h)

The pblock_copy function copies the contents of one parameter block into another.

Syntax

#include <base/pblock.h>
void pblock_copy(pblock *src, pblock *dst);

Returns

void

Parameters

pblock *src is the source parameter block.

pblock *dst is the destination parameter block.

Both entries are newly allocated so that the original parameter block may be freed, or the new parameter block changed, without affecting the other parameter block.

See also

pblock_create, pblock_dup, pblock_free, pblock_find, pblock_remove, pblock_nvinsert

pblock_create (declared in base/pblock.h)

The pblock_create function creates a new parameter block. The system maintains an internal hash table for fast name-value pair lookups.

Syntax

#include <base/pblock.h>
pblock *pblock_create(int n);

Returns

The newly allocated parameter block.

Parameters

int n is the size of the hash table (number of name-value pairs) for the parameter block.

See also

pblock_copy, pblock_dup, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock

pblock_dup (declared in base/pblock.h)

The pblock_dup function duplicates a parameter block. It is equivalent to a sequence of pblock_create and pblock_copy.

Syntax

#include <base/pblock.h>
pblock pblock_dup(pblock *src);

Returns

The newly allocated parameter block.

Parameters

pblock *src is the source parameter block.

See also

pblock_create, pblock_free, pblock_find, pblock_remove, pblock_nvinsert

pblock_find (declared in base/pblock.h)

The pblock_find function finds a specified name-value pair entry in a parameter block and retrieves the name and structure of the parameter block. If you want only the value of the parameter block, use only the function pblock_findval to get the actual value in the name-value pair.

Note that this function is implemented as a macro.

Syntax

#include <base/pblock.h>
pb_param *pblock_find(char *name, pblock *pb);

Returns

• A parameter block structure, if one was found
• NULL if no parameter block was found

Parameters

char *name is the name of a name-value pair.

pblock *pb is the parameter block to be searched.

See also

pblock_copy, pblock_findval, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock

pblock_findlong (declared in libproxy/util.h)

The pblock_findlong function finds a specified name-value pair entry in a parameter block, and retrieves the name and structure of the parameter block. Use pblock_findlong if you want to retrieve the name, structure, and value of the parameter block. However, if you want only the name and structure of the parameter block, use the pblock_find function. Do not use these two functions in conjunction.

Syntax

#include <libproxy/util.h>
long pblock_findlong(char *name, pblock *pb);

Returns

• A long containing the value associated with the name
• -1 if no match was found

Parameters

char *name is the name of a name-value pair.

pblock *pb is the parameter block to be searched.

See also

pblock_nlinsert

pblock_findval (declared in base/pblock.h)

The pblock_findval function finds a specified name-value pair entry in a parameter block. Use pblock_findval if you want to retrieve the name, structure, and value of the parameter block. However, if you want just the name and structure of the parameter block, use only the macro pblock_find.

Syntax

#include <base/pblock.h>
char *pblock_findval(char *name, pblock *pb);

Returns

• A string containing the value associated with the name
• NULL if no match was found

Parameters

char *name is the name of a name-value pair.

pblock *pb is the parameter block to be searched.

Example

See pblock_nvinsert.

See also

pblock_copy, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock

pblock_free (declared in base/pblock.h)

The pblock_free function frees a specified parameter block and any entries inside it. If you want to save a variable in the parameter block, remove the variable using the function pblock_remove and then save the resulting pointer.

Syntax

#include <base/pblock.h>
void pblock_free(pblock *pb);

Returns

void

Parameters

pblock *pb is the parameter block to be freed.

See also

pblock_copy, pblock_create, pblock_find, pblock_nvinsert, pblock_remove, pblock_str2pblock

pblock_nlinsert (declared in libproxy/util.h)

The pblock_nlinsert function creates a new parameter structure with a given name and long numeric value and inserts it into a specified parameter block. The name and value parameters are also newly allocated.

Syntax

#include <libproxy/util.h>
pb_param *pblock_nlinsert(char *name, long value, pblock *pb);

Returns

The newly allocated parameter block structure

Parameters

char *name is the name by which the name-value pair is stored.

long value is the long (or integer) value being inserted into the parameter block.

pblock *pb is the parameter block into which the insertion occurs.

See also

pblock_findlong

pblock_nninsert (declared in base/pblock.h)

The pblock_nninsert function creates a new parameter structure with a given name and a numeric value and inserts it into a specified parameter block. The name and value parameters are also newly allocated.

Syntax

#include <base/pblock.h>
pb_param *pblick_nninsert(char *name, int value, pblock *pb);

Returns

The new parameter block structure

Parameters

char *name is the name by which the name-value pair is stored.

int value is the numeric value being inserted into the parameter block.

The pblock_nninsert function requires that the parameter value be an integer. If the value you assign is not a number, then instead use the function pblock_nvinsert to create the parameter.

pblock *pb is the parameter block into which the insertion occurs.

See also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock

pblock_nvinsert (declared in base/pblock.h)

The pblock_nvinsert function creates a new parameter structure with a given name and character value and inserts it into a specified parameter block. The name and value parameters are also newly allocated.

You could use this function when an error condition is encountered, in order to insert an error into the parameter block argument and to tell initialization routines in the server that an error occurred.

Syntax

#include <base/pblock.h>
pb_param *pblock_nvinsert(char *name, char *value, pblock *pb);

Returns

The newly allocated parameter block structure

Parameters

char *name is the name by which the name-value pair is stored.

char *value is the string value being inserted into the parameter block.

pblock *pb is the parameter block into which the insertion occurs.

Example

int brief_init(pblock *pb, Session *sn, Request *rq)
{
/* find "find" value in the parameter blcock */
    char *fn = pblock_findval("file", pb);
   /* if "file" is not found, insert an "error" value
      asking to supply a filename*/
      if(!fn) {
         pblock_nvinsert("error",
            "brief-init: please supply a filename", pb);
         return REQ_ABORTED;
      }
      /* open a file in write/append mode*/
      logfd = system_fopenWA(fn);
      if(logfd == SYS_ERROR_FD) {
         pblock_nvinsert("error",
         "brief-init: please supply a filename", pb);
      return REQ_ABORTED;
}

See also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nninsert, pblock_remove, pblock_str2pblock

pblock_pb2env (declared in base/pblock.h)

The pblock_pb2env function copies a specified parameter block into a specified environment. The function creates one new environment entry for each name-value pair in the parameter block. Use this function to send pblock entries to a program that you are going to execute.

Syntax

#include <base/pblock.h>
char **pblock_pb2env(pblock *pb, char **env);

Returns

A pointer to the array of name-value pairs.

Parameters

pblock *pb is the parameter block to be copied.

char **env is the environment into which the parameter block is to be copied.

See also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock

pblock_pblock2str (declared in base/pblock.h)

The pblock_pblock2str function copies all parameters of a specified parameter block into a specified string. The function allocates additional non-heap space for the string if needed.

Use this function to stream the parameter block for archival and other purposes.

Syntax

#include <base/pblock.h>
char *pblock_pblock2str(pblock *pb, char *str);

Returns

The new version of the str parameter. If str was NULL, this is a new string; otherwise it is a reallocated string. In either case, it is allocated in the pool of memory established for the current request.

Parameters

pblock *pb is the parameter block to be copied.

char *str is the string into which the parameter block is to be copied. It must have been allocated by MALLOC or REALLOC, not by PERM_MALLOC or PERM_REALLOC (which allocate from the heap).

Each name-value pair in the string is separated from its neighbor pair by a space and is in the format name="value".

See also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock

pblock_pinsert (declared in base/pblock.h)

This function can be used instead of the function pblock_nvinsert. Both functions insert an error into the parameter block argument to tell initialization routines in the server that an error occurred. However, pblock_pinsert is more convenient if you want to insert several parameter structures.

Syntax

#include <base/pblock.h>
void pblock_pinsert(pb_param *pp, pblock *pb);

Returns

void

Parameters

pb_param *pp is the parameter to insert.

pblock *pb is the parameter block.

See also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock

pblock_remove (declared in base/pblock.h)

The pblock_remove function removes a specified name-value entry from a specified parameter block.

Note that this function is implemented as a macro. Furthermore, if you use this macro your code must eventually call param_free in order to deallocate the memory used by the parameter structure.

Syntax

#include <base/pblock.h>
pb_param *pblock_remove(char *name, pblock *pb);

Returns

• The removed parameter block structure, if it was found
• NULL if no parameter block was found

Parameters

char *name is the name portion that identifies the name-value pair to be removed.

pblock *pb is the from which the name-value entry is to be removed. See pblock_free.

See also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_str2pblock

pblock_replace_name (declared in libproxy/util.h)

The pblock_replace_name function replaces the name of a name-value pair, retaining the value.

Syntax

#include <libproxy/util.h>
void pblock_replace_name(char *oname,char *nname, pblock *pb);

Returns

void

Parameters

char *oname is the old name of a name-value pair.

char *nname is the new name for the name-value pair.

pblock *pb is the parameter block to be searched.

See also

pblock_remove

pblock_str2pblock (declared in base/pblock.h)

The pblock_str2pblock function scans a string for parameter pairs, adds the value to a parameter block, and returns the number of parameters added.

Syntax

#include <base/pblock.h>
int pblock_str2pblock(char *str, pblock *pb);

Returns

• The number of parameters pair added to the parameter block, if any
• -1 if an error occurred

Parameters

char *str is the string to be scanned.

The name-value pairs in the string can have the format name=value or name="value".

All backslashes (\) must be followed by a literal character. If string values are found with no unescaped = signs (no name=), it assumes the names 1, 2, 3, and so on, depending on the string position (zero doesn't count). For example, if pblock_str2pblock finds "some" "strings" "together", the function treats the strings as if they appeared in the name-value pairs as 1="some" 2 ="strings" 3="together".

pblock *pb is the parameter block into which all name-value pairs are to be stored.

See also

pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_pblock2str

PERM_FREE (declared in netsite.h)

The PERM_FREE macro is a platform-independent substitute for the C library routine free. It deallocates the persistent space previously allocated by PERM_MALLOC or PERM_STRDUP to a specfied pointer. If memory pooling has been disabled in the configuration file, PERM_FREE and FREE both return memory to the system heap.

Syntax

#include <netsite.h>
PERM_FREE(ptr);

Returns

void

Parameters

ptr is a (void) pointer to an object. If the pointer is not one created by PERM_MALLOC or PERM_STRDUP, the behavior is undefined.

See also

FREE, MALLOC, REALLOC, STRDUP, PERM_MALLOC, PERM_STRTUP

PERM_MALLOC (declared in netsite.h)

The PERM_MALLOC macro is a platform-independent substitute for the C library routine malloc. It provides allocation of memory that persists after the request that was being processed has been completed. If memory pooling has been disabled in the configuration file, PERM_MALLOC and MALLOC both obtain their memory from the system heap.

Syntax

#include <netsite.h>
PERM_MALLOC(size)

Returns

A pointer to space for an object of size size.

Parameters

size (an int) is the number of bytes to allocate.

Example

/* Initialize hosts array */
    num_hosts = 0;
    hosts = (char **) PERM_MALLOC(1 * sizeof(char *));
    hosts[0] = NULL;

See also

MALLOC, REALLOC, FREE, PERM_FREE, STRDUP, PERM_STRDUP

PERM_STRDUP (declared in netsite.h)

The PERM_STRDUP macro is a platform-independent substitute for the common Unix library routine strdup. It creates a new copy of a string in memory that persists after the request that was being processed has been completed. If memory pooling has been disabled in the configuration file, PERM_STRDUP and STRDUP both obtain their memory from the system heap.

The strdup routine is functionally equivalent to

char *newstr = (char *) malloc(strlen(str) + 1);
strcpy(newstr, str);

Syntax

#include <netsite.h>
PERM_STRDUP(ptr);

Returns

A pointer to the new string.

Parameters

ptr is a pointer to a string.

See also

MALLOC, FREE, REALLOC

protocol_dump822 (declared in frame/protocol.h)

The protocol_dump822 function prints headers from a specified parameter block into a specific buffer, with a specified size and position. Use this function to serialize the headers so that they can be sent, for example, in a mail message.

Syntax

#include <frame/protocol.h>
char *protocol_dump822(pblock *pb, char *t, int *pos, int tsz);

Returns

The buffer, reallocated if necessary

The function also modifies pos to denote a new position in the buffer.

Parameters

pblock *pb is the parameter block structure.

char *t is the name of the buffer.

int *pos is the position within the buffer at which the headers are to be inserted.

int *tsz is the size of the buffer.

See also

protocol_handle_session, protocol_scan_headers, protocol_start_response, protocol_status

protocol_finish_request (declared in frame/protocol.h)

The protocol_finish_request function finishes a specified request. For HTTP, the function just closes the socket.

Syntax

#include <frame/protocol.h>
void protocol_finish_request(Session *sn, Request *rq);

Returns

void

Parameters

Session *sn is the Session that generated the request.

Request *rq is the Request to be finished.

See also

protocol_handle_session, protocol_scan_headers, protocol_start_response, protocol_status

protocol_handle_session (declared in frame/protocol.h)

The protocol_handle_session function processes each request generated by a specified session.

Syntax

#include <frame/protocol.h>
void protocol_handle_session(Session *sn);

Parameters

Session *sn is the that generated the requests.

See also

protocol_scan_headers, protocol_start_response, protocol_status

protocol_hdrs2env (declared in frame/protocol.h)

The protocol_hdrs2env function converts the entries in a specified parameter block and converts them to an environment. Use this function to create an environment that a program can later use.

Syntax

#include <frame/protocol.h>
char **protocol_hdrs2env(pblock *pb);

Returns

A pointer to the new environment. Note that each entry is converted to uppercase text with the prefix HTTP_.

A hyphen (-) or double hyphen(--) in the text is automatically converted into an underscore (_), or double underscore (_ _), respectively.

Parameters

pblock *pb is the parameter block.

See also

protocol_handle_session, protocol_scan_headers, protocol_start_response, protocol_status

protocol_parse_request (declared in frame/protocol.h)

Parses the first line of an HTTP request.

Syntax

#include <frame/protocol.h>
int protocol_parse_request(char *t, Request *rq, Session *sn);

Returns

• The constant REQ_PROCEED if the operation succeeded
• The constant REQ_ABORTED if the operation did not succeed

Parameters

char *t defines a string of length REQ_MAX_LINE. This is an optimization for the internal code to reduce usage of runtime stack.

Request *rq is the request to be parsed.

Session *sn is the session that generated the request.

See also

protocol_scan_headers, protocol_start_response, protocol_status

protocol_scan_headers (declared in frame/protocol.h)

Scans HTTP headers from a specified network buffer, and places them in a specified parameter block.

Folded lines are joined and the linefeeds are removed (but not the whitespace). If there are any repeat headers, they are joined and the two field bodies are separated by a comma and space. For example, multiple mail headers are combined into one header and a comma is used to separate the field bodies.

Syntax

#include <frame/protocol.h>
int protocol_scan_headers(Session *sn, netbuf *buf, char *t, pblock *headers);

Returns

• The constant REQ_PROCEED if the operation succeeded
• The constant REQ_ABORTED if the operation did not succeed

Parameters

Session *sn is the session that generated the request. The structure named by sn contains a pointer to a netbuf called inbuf. If the parameter buf is NULL, the function automatically uses inbuf.

Note that sn is an optional parameter that is used for error logs. Use NULL if you wish.

netbuf *buf is the network buffer to be scanned for HTTP headers.

char *t defines a string of length REQ_MAX_LINE. This is an optimization for the internal code to reduce usage of runtime stack.

pblock *headers is the parameter block to receive the headers.

See also

protocol_handle_session, protocol_start_response, protocol_status

protocol_set_finfo (declared in frame/protocol.h)

The protocol_set_finfo function retrieves the content-length and last-modified date from a specified stat structure, for a specified Session and the Request generated by that Session. Use protocol_set_finfo only after receiving a start_response from a service-class server application function (SAF).

Syntax

#include <frame/protocol.h>
int protocol_set_finfo(Session *sn, Request *rq, struct stat *finfo);

Returns

• The constant REQ_PROCEED if the Request can proceed normally
• The constant REQ_ABORTED if the function should treat the Request normally but not send any output to the client

Parameters

Session *sn is the Session that generated the Request.

Request *rq is the Request.

stat *finfo is the stat structure for the file.

The stat structure contains the information about the file you are sending back to the client. The full description of the stat structure should be available from the documentation for your system. For the basic elements of the stat structure, see "The Stat Data Structure".

See also

protocol_handle_session, protocol_scan_headers, protocol_start_response, protocol_status

protocol_start_response (declared in frame/protocol.h)

The protocol_start_response function initiates the HTTP response for a specified Session and Request. If the protocol version is HTTP/0.9, the function does nothing, because that version has no concept of status. If the protocol version is HTTP/1.0, the function sends a status line followed by the response headers. Use this function to set up HTTP and prepare the client and server to receive the body (or data) of the response.

Syntax

#include <frame/protocol.h>
int protocol_start_response(Session *sn, Request *rq);

Returns

• The constant REQ_PROCEED if the operation succeeded, in which case you can send the data you were preparing to send
• The constant REQ_NOACTION if the operation succeeded, but the client has requested that the server not send the data because the client has it in cache
• The constant REQ_ABORTED if the operation did not succeed

Parameters

Session *sn is the Session that generated the Request.

Request *rq is the Request to which a response is being started.

Example

/* A noaction response from this function means the request was HEAD */
if(protocol_start_response(sn, rq) == REQ_NOACTION) {
   filebuf_close(groupbuf); /* this also closes fd */
   return REQ_PROCEED;
}

See also

protocol_handle_session, protocol_scan_headers, protocol_status

protocol_status (declared in frame/protocol.h)

The protocol_status function sets the Session status to indicate whether an error condition occurred. If the reason string is NULL, the server attempts to find a reason string for the given status code. If it finds none, it returns "Unknown reason." This reason string is sent to the client in the status line. Use this function to set the status of the Session before calling the function protocol_start_response.

These are valid status codes:

PROTOCOL_OK
PROTOCOL_NO_RESPONSE
PROTOCOL_REDIRECT
PROTOCOL_NOT_MODIFIED
PROTOCOL_BAD_REQUEST
PROTOCOL_UNAUTHORIZED
PROTOCOL_FORBIDDEN
PROTOCOL_NOT_FOUND
PROTOCOL_PROXY_UNAUTHORIZED
PROTOCOL_SERVER_ERROR
PROTOCOL_NOT_IMPLEMENTED

Syntax

#include <frame/protocol.h>
void protocol_status(Session *sn, Request *rq, int n, char *r);

Returns

void, but sets values in the Session/Request designated by sn/rq for the status code and the reason string

Parameters

Session *sn is the Session that generated the Request.

Request *rq is the Request that is being checked on.

int n is the value to which to set the status code.

char *r is the reason string.

Example

if( (t = pblock_findval("path-info", rq->vars)) ) {
    protocol_status(sn, rq, PROTOCOL_NOT_FOUND, NULL);
    log_error(LOG_WARN, "send-images", sn, rq,
               "%s%s not found", path, t);
    return REQ_ABORTED;
}

See also

protocol_handle_session, protocol_scan_headers, protocol_start_response

protocol_uri2url (declared in frame/protocol.h)

The protocol_uri2url function takes strings containing the given URI prefix and URI suffix and creates a newly allocated fully qualified URL in the form http://(server):(port)(prefix)(suffix).

If you want to omit either the URI prefix or suffix, use "" instead of NULL as the value for either parameter. To redirect the client somewhere else, use the function pblock_nvinsert to create a new entry in the vars in the pblock in your Request structure.

Syntax

#include <frame/protocol.h>
char *protocol_uri2url(char *prefix, char *suffix);

Returns

A new string containing the URL

Parameters

char *prefix is the prefix.

char *suffix is the suffix.

See also

protocol_handle_session, protocol_scan_headers, protocol_start_response, protocol_status

protocol_uri2url_dynamic (declared in frame/protocol.h)

The protocol_uri2url function takes strings containing the given URI prefix and URI suffix and creates a newly allocated fully qualified URL in the form http://(server):(port)(prefix)(suffix).

If you want to omit either the URI prefix or suffix, use "" instead of NULL as the value for either parameter. To redirect the client somewhere else, use the function pblock_nvinsert to create a new entry in the vars in the pblock in your Request structure.

The protocol_uri2url_dynamic function is exactly like the protocol_uri2url function, but should be used whenever the Session and Request structures are available. This ensures that the URL that it constructs refers to the host that the client specified.

Syntax

#include <frame/protocol.h>
char *protocol_uri2url(char *prefix, char *suffix, Session *sn, Request *rq);

Returns

A new string containing the URL

Parameters

char *prefix is the prefix.

char *suffix is the suffix.

Session *sn is the Session that generated the Request.

Request *rq is the Request that is being processed.

See also

protocol_handle_session, protocol_scan_headers, protocol_start_response, protocol_status

REALLOC (declared in netsite.h)

The REALLOC macro is a platform-independent substitute for the C library routine realloc. It changes the size of a specfied object that was originally created by MALLOC or STRDUP. The contents of the object remain unchanged up to the minimum of the old and new sizes. If the new size is larger, the new space is uninitialized.

---

Note	Calling REALLOC for a block that was allocated with PERM_MALLOC will not work.

---

Syntax

#include <netsite.h>
REALLOC(ptr, size);

Returns

A pointer to the new space if the Request could be satisfied.

Parameters

ptr is a (void) pointer to an object. If the pointer is not one created by MALLOC or STRDUP, the behavior is undefined.

size (an int) is the number of bytes to allocate.

Example

while(fgets(buf, MAX_ACF_LINE, f)) {
/* Blast linefeed that stdio leaves on there */
   uf[strlen(buf) - 1] = '\0';
   hosts = (char **) REALLOC(hosts, (num_hosts + 2) * sizeof(char *));
   hosts[num_hosts++] = STRDUP(buf);
   hosts[num_hosts] = NULL;
}

See also

MALLOC, FREE, STRDUP

request_create (declared in frame/req.h)

The request_create function is a utility function that creates a new request structure.

Syntax

#include <frame/req.h>
Request *request_create(void);

Returns

A Request structure

Parameters

No parameter is required.

See also

request_free, request_header

request_free (declared in frame/req.h)

The request_free function frees a specified request structure.

Syntax

#include <frame/req.h>
void request_free(Request *req);

Returns

void

Parameters

Request *rq is the Request structure to be freed.

See also

request_header

request_header (declared in frame/req.h)

The request_header function finds the parameter block containing the client's HTTP headers. You can use this function to access a parameter block indirectly, thereby avoiding multiple and unnecessary calls. In addition, request_header allows you to access the parameter block headers in your copy of the request structure.

Syntax

#include <frame/req.h>
int request_header(char *name, char **value, Session *sn, Request *rq);

Returns

A REQ return code, such as REQ_ABORTED to signal that an error occurred, or REQ_PROCEED to signal that all went well

Parameters

char *name is the name of the header.

char **value is the address where the function will place the value of the specified header. If none is found, the function stores a NULL.

Session *sn is the Session identifier for the server application function call that generated the Request.

Request *rq is the Request identifier for a server application function call.

The sn and rq parameters can also be used to identify a specific Request in asynchronous operations as well as for other internal housekeeping purposes.

Example

See shexp_cmp.

See also

request_create, request_free

request_stat_path (declared in frame/req.h)

The request_stat_path function returns the file information structure for a specified path, if none is specified, the path entry in the vars pblock in a specified Request structure. If the resulting filename points to a file that the server can read, request_stat_path returns a new file information structure. This structure contains information on the size of the file, when it was last accessed, and when it was last changed.

You can use request_stat_path to retrieve information on the file you are currently accessing (instead of calling stat directly), because this function keeps track of other calls.

Syntax

#include <frame/req.h>
struct stat *request_stat_path(char *path, Request *rq);

Returns

• NULL if the file is not valid or the server cannot read it. In this case, it also leaves an error message describing the problem in the Request structure denoted by rq.
• The file information structure for the file named by the path parameter.

If you receive a valid file information structure, you should not free this structure.

Parameters

char *path is the string containing the name of the path. If the value of path is NULL, the function uses the path entry in the vars pblock in the Request structure denoted by rq.

Request *rq is the Request identifier for a server application function call.

Example

if( (!(fi = request_stat_path(path, rq)) ) ||
( (fd = system_fopenRO(path)) == IO_ERROR) )

See also

request_create, request_free, request_header

request_translate_uri (declared in frame/req.h)

The request_translate_uri function performs virtual-to-physical mapping on a specified URI during a specified Session. Use this function when you want to determine which file will be sent back if a given URI is accessed.

Syntax

#include <frame/req.h>
char *request_translate_uri(char *uri, Session *sn);

Returns

• A path string, if it performed the mapping
• NULL if it could not perform the mapping

Parameters

char *uri is the name of the URI.

Session *sn is the Session identifier for the server application function call.

See also

request_create, request_free, request_header

sem_grab (declared in base/sem.h)

The sem_grab function requests exclusive access to a specified semaphore. If exclusive access is unavailable, the caller blocks execution until exclusive access becomes available. Use this function to ensure that only one server processor thread performs an action at a time.

Syntax

#include <base/sem.h>
int sem_grab(SEMAPHORE id);

Returns

• -1 if an error occurred
• 0 to signal success

Parameters

SEMAPHORE id is the unique identification number of the requested semaphore.

See also

sem_init, sem_release, sem_terminate, sem_tgrab

sem_init (declared in base/sem.h)

The sem_init function creates a semaphore with a specified name and unique identification number. Use this function to allocate a new semaphore that will be used with the functions sem_grab and sem_release. Call sem_init from an init class function to initialize a static or global variable that the other classes will later use.

Syntax

#include <base/sem.h>
SEMAPHORE sem_init(char *name, int number);

Returns

The constant SEM_ERROR if an error occurred.

Parameters

SEMAPHORE *name is the name for the requested semaphore. The filename of the semaphore should be a file accessible to the process.

int number is the unique identification number for the requested semaphore.

See also

sem_grab, sem_release, sem_terminate

sem_release (declared in base/sem.h)

The sem_release function releases the process's exclusive control over a specified semaphore. Use this function to release exclusive control over a semaphore created with the function sem_grab.

Syntax

#include <base/sem.h>
int sem_release(SEMAPHORE id);

Returns

• -1 if an error occurred
• 0 of no error occurred

Parameters

SEMAPHORE id is the unique identification number of the semaphore.

See also

sem_grab, sem_init, sem_terminate

sem_terminate (declared in base/sem.h)

The sem_terminate function deallocates the semaphore specified by id. You can use this function to deallocate a semaphore that was previously allocated with the function sem_init.

Syntax

#include <base/sem.h>
void sem_terminate(SEMAPHORE id);

Returns

void

Parameters

SEMAPHORE id is the unique identification number of the semaphore.

See also

sem_grab, sem_init, sem_release

sem_tgrab (declared in base/sem.h)

The sem_tgrab function tests and requests exclusive use of a semaphore. Unlike the somewhat similar sem_grab function, if exclusive access is unavailable the caller is not blocked but receives a return value of -1. Use this function to ensure that only one server processor thread performs an action at a time.

Syntax

#include <base/sem.h>
int sem_grab(SEMAPHORE id);

Returns

• -1 if an error occurred or if exclusive access was not available
• 0 exclusive access was granted

Parameters

SEMAPHORE id is the unique identification number of the semaphore.

See also

sem_grab, sem_init, sem_release, sem_terminate

session_create (declared in base/session.h)

The session_create function creates a new Session structure for the client with a specified socket descriptor and a specified socket address. It returns a pointer to that structure.

Syntax

#include <base/session.h>
Session *session_create(SYS_NETFD csd, struct sockaddr_in *sac);

Returns

• A pointer to the new Session if one was created
• NULL if no new Session was created

Parameters

SYS_NETFDcsd is the platform-independent socket descriptor.

sockaddr_in *sac is the socket address.

See also

session_maxdns

session_free (declared in base/session.h)

The session_free function frees a specified Session structure. The session_free function does not close the client socket descriptor associated with the Session.

Syntax

#include <base/session.h>
void session_free(Session *sn);

Returns

void

Parameters

Session *sn is the Session to be freed.

See also

session_create, session_maxdns

session_maxdns (declared in base/session.h)

The session_maxdns function resolves the IP address of the client associated with a specified Session into a host name. It returns a string. You can use session_maxdns to change the numeric IP address into something more readable. Use session_maxdns instead of the function session_dns if you want to be sure that the host name is associated with the IP address of the client.

This function is implemented as a macro.

Syntax

#include <base/session.h>
char *session_maxdns(Session *sn);

Returns

• A string containing the host name
• NULL if no host name was associated with the IP address

Parameters

Session *sn is the Session identifier for the server application function call.

shexp_casecmp (declared in base/shexp.h)

The shexp_casecmp function validates a specified shell expression and compares it with a specified string. It returns one of three possible values representing match, no match, and invalid comparison. In contrast with the shexp_cmp function, the comparison is not case-sensitive.

Use this function if you have a shell expression like *.netscape.com and you want to make sure that a string matches it, such as foo.netscape.com.

Syntax

#include <base/shexp.h>
int shexp_casecmp(char *str, char *exp);

Returns

• 0 if a match was found
• 1 if no match was found
• -1 if the comparison resulted in an invalid expression

Parameters

char *str is the string to be compared.

char *exp is the shell expression (possibly containing wildcard characters) against which to compare.

See also

shexp_cmp, shexp_match

shexp_cmp (declared in base/shexp.h)

The shexp_cmp function validates a specified shell expression and compares it with a specified string. It returns one of three possible values representing match, no match, and invalid comparison. In contrast with the shexp_casecmp function, the comparison is case-sensitive.

Use this function if you have a shell expression like *.netscape.com and you want to make sure that a string matches it, such as foo.netscape.com.

Syntax

#include <base/shexp.h>
int shexp_cmp(char *str, char *exp);

Returns

• 0 if a match was found
• 1 if no match was found
• -1 if the comparison resulted in an invalid expression

Parameters

char *str is the string to be compared.

char *exp is the shell expression (possibly containing wildcard characters) against which to compare.

Example

#include "base/util.h" /* is_mozilla */
#include "frame/protocol.h" /* protocol_status */
#include "base/shexp.h" /* shexp_cmp */
int https_redirect(pblock *pb, Session *sn, Request *rq)
{
   /* Server Variable */
   char *ppath = pblock_findval("ppath", rq->vars);
   /* Parameters */
   char *from = pblock_findval("from", pb);
   char *url = pblock_findval("url", pb);
   char *alt = pblock_findval("alt", pb);
   /*    
   /* Check usage */
   if((!from) || (!url)) {
   log_error(LOG_MISCONFIG, "https-redirect", sn, rq,
      "missing parameter (need from, url)");
      return REQ_ABORTED;
   }
   /* Use wildcard match to see if this path is one to redirect */
   if(shexp_cmp(ppath, from) != 0)
      return REQ_NOACTION; /* no match */
      /* The only way to check for SSL capability is to check UA */
   if(request_header("user-agent", &ua, sn, rq) == REQ_ABORTED)
   return REQ_ABORTED;
   /* The is_mozilla fn checks for Mozilla version 0.96 or greater */
   f(util_is_mozilla(ua, "0", "96")) {
      /* Set the return code to 302 Redirect */
      protocol_status(sn, rq, PROTOCOL_REDIRECT, NULL);
         /* The error handling fns use this to set Location: */
      pblock_nvinsert("url", url, rq->vars);
      return REQ_ABORTED;
   }
   /* No match. Old client. */
   /* If there is an alternate document specified, use it. */
   if(alt) {
      pb_param *pp = pblock_find("ppath", rq->vars);
      /* Trash the old value */
      FREE(pp->value);
      /* Dup it because the library will later free this pblock */
      pp->value = STRDUP(alt);
      return REQ_PROCEED;
   }
   /* Else do nothing */
   return REQ_NOACTION;
}

See also

shexp_casecmp, shexp_match

shexp_match (declared in base/shexp.h)

The shexp_match function compares a specified prevalidated shell expression against a specified string. It returns one of three possible values representing match, no match, and invalid comparison. In contrast with the shexp_casecmp function, the comparison is case-sensitive.

The shexp_match function doesn't perform validation of the shell expression; instead the function assumes that you have already called shexp_valid.

Use this function if you have a shell expression like *.netscape.com and you want to make sure that a string matches it, such as foo.netscape.com.

Syntax

#include <base/shexp.h>
int shexp_match(char *str, char *exp);

Returns

• 0 if a match was found
• 1 if no match was found
• -1 if the comparison resulted in an invalid expression

Parameters

char *str is the string to be compared.

char *exp is the prevalidated shell expression (possibly containing wildcard characters) against which to compare.

See also

shexp_casecmp, shexp_cmp

shexp_valid (declared in base/shexp.h)

The shexp_valid function validates a specified shell expression named by exp. Use this function to validate a shell expression before using the function shexp_match to compare the expression with a string.

Syntax

#include <base/shexp.h>
int shexp_valid(char *exp);

Returns

• The constant NON_SXP if exp is a standard string
• The constant INVALID_SXP if exp is a shell expression but invalid
• The constant VALID_SXP if exp is a valid shell expression

Parameters

char *exp is the prevalidated shell expression (possibly containing wildcard characters) to be used later in a shexp_match comparison.

See also

shexp_casecmp, shexp_match, shexp_cmp

shmem_alloc (declared in base/shmem.h)

The shmem_alloc function allocates a region of shared memory of the given size, using the given name to avoid conflicts between multiple regions in the program. The size of the region will not be automatically increased if its boundaries are overrun; use the shmem_realloc function for that.

This function must be called before any daemon workers are spawned in order for the handle to the shared region to be inherited by the children.

Because of the requirement that the region must be inherited by the children, the region cannot be reallocated with a larger size when necessary.

Syntax

#include <base/shmem.h>
shmem_s *shmem_alloc(char *name, int size, int expose);

Returns

A pointer to a new shared memory region.

Parameters

char *name is the name for the region of shared memory being created. The value of name must be unique to the program that calls the shmem_alloc function or conflicts will occur.

int size is the number of characters of memory to be allocated for the shared memory.

int expose is either zero or nonzero. If nonzero, then on systems that support it, the file that is used to create the shared memory becomes visible to other processes running on the system.

See also

shmem_free

shmem_free (declared in base/shmem.h)

The shmem_free function deallocates (frees) the specified region of memory.

Syntax

#include <base/shmem.h>
void *shmem_free(shmem_s *region);

Returns

void

Parameters

shmem_s *region is a shared memory region to be released.

See also

shmem_allocate

STRDUP (declared in netsite.h)

The STRDUP macro is a platform-independent substitute for the common Unix library routine strdup. It creates a new copy of a string.

The strdup routine is functionally equivalent to this:

char *newstr = (char *) MALLOC(strlen(str) + 1);
strcpy(newstr, str);

Syntax

#include <netsite.h>
STRDUP(ptr);

Returns

A pointer to the new string.

Parameters

ptr is a pointer to a string.

Example

while(fgets(buf, MAX_ACF_LINE, f)) {
/* Blast linefeed that stdio leaves on there */
   uf[strlen(buf) - 1] = '\0';
   hosts = (char **) REALLOC(hosts, (num_hosts + 2) * sizeof(char *));
   hosts[num_hosts++] = STRDUP(buf);
   hosts[num_hosts] = NULL;
}

See also

MALLOC, FREE, REALLOC

systhread_attach (declared in base/systhr.h)

The systhread_attach function makes an existing thread a platform-independent thread.

Syntax

#include <base/systhr.h>
SYS_THREAD systhread_attach(void);

Returns

A SYS_THREAD pointer to the platform-independent thread.

Parameters

void

See also

systhread_current, systhread_getdata, systhread_init, systhread_newkey, systhread_setdata, systhread_sleep,systhread_start, systhread_terminate, systhread_ timerset

systhread_current (declared in base/systhr.h)

The systhread_current function returns a pointer to the current thread.

Syntax

#include <base/systhr.h>
SYS_THREAD systhread_current(void);

Returns

A SYS_THREAD pointer to the current thread

Parameters

void

See also

systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep,systhread_start, systhread_terminate, systhread_ timerset

systhread_getdata (declared in base/systhr.h)

The systhread_getdata function gets data that is associated with a specified key in the current thread

Syntax

#include <base/systhr.h>
void *systhread_getdata(int key);

Returns

• A pointer to the data that was earlier used with the systhread_setkey function from the current thread, using the same value of key.
• NULL if the call did not succeed, for example if the systhread_setkey function was never called with the specified key during this session.

Parameters

int key is the value associated with the stored data by a systhread_setdata function. Keys are assigned by the systhread_newkey function.

See also

systhread_current, systhread_newkey, systhread_setdata, systhread_sleep,systhread_start, systhread_terminate, systhread_ timerset

systhread_init (declared in base/systhr.h)

The systhread_init function initializes the threading system.

Syntax

#include <base/systhr.h>
void systhread_init(char *name);

Returns

void

Parameters

char *name is a name to be assigned to the program for debugging purposes.

See also

systhread_attach, systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep,systhread_start, systhread_terminate, systhread_ timerset

systhread_newkey (declared in base/systhr.h)

The systhread_newkey function allocates a new integer key (identifier) for thread-private data. Use this key to identify a variable that you want to localize to the current thread, then use the systhread_setdata function to associate a value with the key.

Syntax

#include <base/systhr.h>
int systhread_newkey(void);

Returns

An integer key.

Parameters

void

See also

systhread_current, systhread_getdata, systhread_setdata, systhread_sleep, systhread_start, systhread_terminate, systhread_ timerset

systhread_setdata (declared in base/systhr.h)

The systhread_setdata function associates data with a specified key number for the current thread. Keys are assigned by the systhread_newkey function.

Syntax

#include <base/systhr.h>
void systhread_start(int key, void *data);

Returns

void

Parameters

int key is the priority of the thread.

void *data is the pointer to the string of data to be associated with the value of key.

See also

systhread_current, systhread_getdata, systhread_newkey, systhread_sleep, systhread_start, systhread_terminate, systhread_ timerset

systhread_sleep (declared in base/systhr.h)

The systhread_sleep function puts the calling thread to sleep for a given time.

Syntax

#include <base/systhr.h>
void systhread_sleep(int milliseconds);

Returns

void

Parameters

int milliseconds is the number of milliseconds the thread is to sleep.

See also

systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_start, systhread_terminate, systhread_ timerset

systhread_start (declared in base/systhr.h)

The systhread_start function creates a thread with the given priority, allocates a stack of a specified number of bytes, and calls a specified function with a specified argument.

Syntax

#include <base/systhr.h>
SYS_THREAD systhread_start(int prio, int stksz, void (*fn)(void *), void *arg);

Returns

• A new SYS_THREAD pointer if the call succeeded
• The constant SYS_THREAD_ERROR if the call did not succeed.

Parameters

int prio is the priority of the thread. Priorities are system-dependent.

int stksz is the stack size in bytes. If stksz is zero, the function allocates a default size.

void (*fn)(void *) is the function to call.

void *arg is the argument for the fn function.

See also

systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep, systhread_terminate, systhread_ timerset

systhread_terminate (declared in base/systhr.h)

The systhread_terminate function terminates a specified thread.

Syntax

#include <base/systhr.h>
void systhread_terminate(SYS_THREAD thr);

Returns

void

Parameters

SYS_THREAD thr is the thread to terminate.

See also

systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep, systhread_start, systhread_ timerset

systhread_timerset (declared in base/systhr.h)

The systhread_timerset function starts or resets the interrupt timer interval for a thread system.

---

Note	Because most systems don't allow the timer interval to be changed, this should be considered a suggestion, rather than a command.

---

Syntax

#include <base/systhr.h>
void systhread_timerset(int usec);

Returns

void

Parameters

int usec is the time, in microseconds

See also

systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep,systhread_start, systhread_terminate

system_errmsg (declared in base/file.h)

The system_errmsg function returns the last error that occurred from the most recent system call. This function is implemented as a macro that returns an entry from the global array sys_errlist. Use this macro to help with I/O error diagnostics.

Syntax

#include <base/file.h>
char *system_errmsg(int para1);

Returns

A string containing the text of the latest error message that resulted from a system call.

Parameters

int para1 is reserved and should always have the value zero.

See also

system_fclose, system_fread, system_fopenRO, system_fwrite

system_fclose (declared in base/file.h)

The system_fclose function closes a specified file descriptor. The system_fclose function must be called for every file descriptor opened by any of the system_fopen functions.

Syntax

#include <base/file.h>
int system_fclose(SYS_FILE fd);

Returns

• 0 if the close succeeded
• The constant IO_ERROR if the close failed

Parameters

SYS_FILE fd is the platform-independent file descriptor.

Example

static SYS_FILE logfd = SYS_ERROR_FD;
// this function closes global logfile
void brief_terminate()
{
   system_fclose(logfd);
   logfd = SYS_ERROR_FD;
}

See also   

system_errmsg, system_fread, system_fopenRO, system_fwrite

system_flock (declared in base/file.h)

The system_flock function locks the specified file against interference from other processes. Use system_flock if you do not want other processes using the file you currently have open. Overusing file locking can cause performance degradation and possibly lead to deadlocks.

Syntax

#include <base/file.h>
int system_flock(SYS_FILE fd);

Returns

• The constant IO_OK if the lock succeeded
• The constant IO_ERROR if the lock failed

Parameters

SYS_FILE fd is the platform-independent file descriptor.

See also

system_fclose, system_fread, system_fopenRO, system_fwrite, system_ulock

system_fopenRO (declared in base/file.h)

The system_fopenRO function opens the file identified by path in read-only mode and returns a valid file descriptor. Use this function to open files that will not be modified by your program. In addition, you can use system_fopenRO to open a new file buffer structure using filebuf_open.

Syntax

#include <base/file.h>
SYS_FILE system_fopenRO(char *path);

Returns

• The system-independent file descriptor (SYS_FILE) if the open succeeded
• 0 if the open failed

Parameters

char *path is the filename.

See also

system_fclose, system_fread, system_fopenRW, system_fopenWA, system_fwrite, system_ulock

system_fopenRW (declared in base/file.h)

The system_fopenRW function opens the file identified by path in read-write mode and returns a valid file descriptor. If the file already exists, system_fopenRW does not truncate it. Use this function to open files that will be read from and written to by your program.

Syntax

#include <base/file.h>
SYS_FILE system_fopenRW(char *path);

Returns

• The system-independent file descriptor (SYS_FILE) if the open succeeded
• 0 if the open failed

Parameters

char *path is the filename.

Example

/* If any errors, just skip it. */
if(stat(pathname, &finfo) == -1)
   break;

fd = system_fopenRO(pathname);
if(fd == SYS_ERROR_FD)
   break;

See also

system_fclose, system_fread, system_fopenRO, system_fopenWA, system_fwrite, system_ulock

system_fopenWA (declared in base/file.h)

The system_fopenWA function opens the file identified by path in append mode and returns a valid file descriptor. Use this function to open those files to which your program will append data.

Syntax

#include <base/file.h>
SYS_FILE system_fopenWA(char *path);

Returns

• The system-independent file descriptor (SYS_FILE) if the open succeeded
• 0 if the open failed

Parameters

char *path is the filename.

See also

system_fclose, system_fread, system_fopenRO, system_fopenRW, system_fwrite, system_ulock

system_fread (declared in base/file.h)

The system_fread function reads a specified number of bytes from a specified file into a specified buffer. It returns the number of bytes read. Before system_fread can be used, you must open the file using any of the system_fopen functions, except system_fopenWA.

Syntax

#include <base/file.h>
int system_fread(SYS_FILE fd, char *buf, int sz);

Returns

The number of bytes read, which may be less than the requested size if an error occurred or the end of the file was reached before that number of characters was obtained.

Parameters

SYS_FILE fd is the platform-independent file descriptor.

char *buf is the buffer to receive the bytes.

int sz is the number of bytes to read.

See also

system_fclose, system_fopenRO, system_fopenRW, system_fopenWA, system_fwrite, system_ulock

system_fwrite (declared in base/file.h)

The system_fwrite function writes a specified number of bytes from a specified buffer into a specified file. Before system_fwrite can be used, you must open the file using any of the system_fopen functions, except system_fopenRO.

Syntax

#include <base/file.h>
int system_fwrite(SYS_FILE fd, char *buf, int sz);

Returns

• The constant IO_OK if the write succeeded
• The constant IO_ERROR if the write failed

Parameters

SYS_FILE fd is the platform-independent file descriptor.

char *buf is the buffer containing the bytes to be written.

int sz is the number of bytes to write to the file.

See also

system_fclose, system_fopenRO, system_fopenRW, system_fopenWA, system_fwrite_atomic, system_ulock

system_fwrite_atomic (declared in base/file.h)

The system_fwrite_atomic function writes a specified number of bytes from a specified buffer into a specified file. The function also locks the file prior to performing the write and then unlocks it when done, thereby avoiding interference between simultaneous write actions. Before system_fwrite_atomic can be used, you must open the file using any of the system_fopen functions.

Syntax

#include <base/file.h>
int system_fwrite_atomic(SYS_FILE fd, char *buf, int sz);

Returns

• The constant IO_OK if the write/lock succeeded
• The constant IO_ERROR if the write/lock failed

Parameters

SYS_FILE fd is the platform-independent file descriptor.

char *buf is the buffer containing the bytes to be written.

int sz is the number of bytes to write to the file.

Example

logmsg = (char *)
   MALLOC(strlen(ip) + 1 + strlen(method) + 1 + strlen(uri) + 1 + 1);
len = util_sprintf(logmsg, "%s %s %s\n", ip, method, uri);
/* The atomic version uses locking to prevent interference */
system_fwrite_atomic(logfd, logmsg, len);
FREE(logmsg);

See also

system_fclose, system_fopenRO, system_fopenRW, system_fopenWA, system_fwrite, system_ulock

system_gmtime (declared in base/file.h)

The system_gmtime function is a thread-safe version of the standard gmltime function.

Syntax

#include <base/file.h>
struct tm *system_gmtime(const time_t *tp, const struct tm *res);

Returns

a pointer to a calendar time (tm) structure containing the GMT time. Depending on your system, the pointer may point to the data item represented by the second parameter, or it may point to a statically allocated item. For portability, do not assume either situation.

Parameters

time_t *tp is an arithmetic time.

tm *res is a pointer to a calendar time (tm) structure.

Example

time_t tp;
struct tm res, *resp;
...
tp = time(NULL);
resp = system_gmtime(&tp, &res);

See also

system_localtime

system_localtime (declared in base/file.h)

The system_localtime function is a thread-safe version of the standard localtime function.

Note that this function is implemented as a macro.

Syntax

#include <base/file.h>
struct tm *system_localtime(const time_t *tp, const struct tm *res);

Returns

a pointer to a calendar time (tm) structure containing the local time. Depending on your system, the pointer may point to the data item represented by the second parameter, or it may point to a statically allocated item. For portability, do not assume either situation.

Parameters

time_t *tp is an arithmetic time.

tm *res is a pointer to a calendar time (tm) structure.

Example

time_t tp;
struct tm res, *resp;
...
tp = time(NULL);
resp = system_localtime(&tp, &res);

See also

system_gmtime

system_ulock (declared in base/file.h)

The system_ulock function unlocks the specified file that has been locked by the function system_lock. For more information about locking, see system_flock.

Syntax

#include <base/file.h>
int system_ulock(SYS_FILE fd);

Returns

• The constant IO_OK if the unlock succeeded
• The constant IO_ERROR if the unlock failed

Parameters

SYS_FILE fd is the platform-independent file descriptor.

See also

system_fclose, system_flock, system_fopenRO, system_fopenRW, system_fopenWA, system_fwrite

system_unix2local (declared in base/file.h)

The system_unix2local function converts a specified Unix-style pathname to a local pathname named by lp. Use this function when you have a filename in the Unix format (such as one containing forward slashes) and you are running Windows NT. You can use system_unix2local to convert the Unix filename into the format that Windows NT accepts. In the Unix environment, this function does nothing.

Syntax

#include <base/file.h>
char *system_unix2local(char *path, char *lp);

Returns

A pointer to the local path string

Parameters

char *path is the Unix-style pathname to be converted.

char *lp is the local pathname.

You must allocate the parameter lp, and it must contain enough space to hold the local pathname.

See also

system_fclose, system_flock, system_fopenRO, system_fopenRW, system_fopenWA, system_fwrite

util_can_exec (declared in base/util.h)

The util_can_exec function checks that a specified file can be executed, returning either a 1 (executable) or a 0. The function checks to see if the file can be executed by the user with the given user and group ID.

The util_can_exec function is available only under Unix.

Use this function before executing a program using the exec system call.

Syntax

#include <base/util.h>
int util_can_exec(struct stat *finfo, uid_t uid, gid_t gid);

Returns

• 1 if the file is executable
• 0 if the file is not executable

Parameters

stat *finfo is the stat structure associated with a file.

uid_t uid is the Unix user ID.

gid_t gid is the Unix group ID. Together with uid, this determines the permissions of the Unix user.

See also

util_env_create, util_getline, util_host name

util_chdir2path (declared in base/util.h)

The util_chdir2path function changes the current directory to a specified directory, which should point to a file.

When running under Windows NT, use a semaphore to ensure that more than one thread does not call this function at the same time.

Use util_chdir2path when you want to make file access a little quicker, because you do not need to use a full path with this function.

Syntax

#include <base/util.h>
int util_chdir2path(char *path);

Returns

• 0 if the directory was changed
• -1 if the directory could not be changed

Parameters

char *path is the name of a directory.

The parameter must be a writable string because it isn't permanently modified.

See also

util_env_create, util_getline, util_host name

util_does_process_exist (declared in libproxy/util.h)

The util_does_process_exist function verifies that a given process ID is that of an executing process.

Syntax

#include <libproxy/til.h>
int util_does_process_exist (int pid)

Returns

• nonzero if the pid represents an executing process
• 0 if the pid does not represent an executing process

Parameters

int pid is the process ID to be tested.

See also

util_url_fix_host name, util_uri_check

util_env_create (declared in base/util.h)

The util_env_create function creates and allocates the environment specified by env, returning a pointer to the environment. If the parameter env is NULL, the function allocates a new environment. Use util_env_create to create an environment when executing a new program.

Syntax

#include <base/util.h>
char **util_env_create(char **env, int n, int *pos);

Returns

A pointer to an environment.

Parameters

char **env is the existing environment or NULL.

int n is the maximum number of environment entries that you want in the environment.

int *pos is an integer that keeps track of the number of entries used in the environment.

See also

util_env_replace, util_env_str, util_env_free, util_env_find

util_env_find (declared in base/util.h)

The util_env_find function locates the string denoted by a name in a specified enviroment and returns the associated value. Use this function to find an entry in an environment.

Syntax

#include <base/util.h>
char *util_env_find(char **env, char *name);

Returns

• The value of the string, if one was found
• NULL if the string was not found

Parameters

char **env is the environment.

char *name is the name of a name-value pair.

See also

util_env_replace, util_env_str, util_env_free, util_env_create

util_env_free (declared in base/util.h)

The util_env_free function frees a specified environment. Use this function to deallocate an environment that you created using the function util_env_create.

Syntax

#include <base/util.h>
void util_env_free(char **env);

Returns

void

Parameters

char **env is the environment to be freed.

See also

util_env_replace, util_env_str, util_env_find, util_env_create

util_env_replace (declared in base/util.h)

The util_env_replace function replaces the occurrence of the variable denoted by a name in a specified environment with a specified value. Use this function to change the value of a setting in an environment.

Syntax

#include <base/util.h>
void util_env_replace(char **env, char *name, char *value);

Returns

void

Parameters

char **env is the environment.

char *name is the name of a name-value pair.

char *value is the new value to be stored.

See also

util_env_str, util_env_free, util_env_find, util_env_create

util_env_str (declared in base/util.h)

The util_env_str function creates an environment entry and returns it. This function does not check for nonalphanumeric symbols in the name (such as the equal sign "="). You can use this function to create a new environment entry.

Syntax

#include <base/util.h>
char *util_env_str(char *name, char *value);

Returns

A newly allocated string containing the name-value pair

Parameters

char *name is the name of a name-value pair.

char *value is the new value to be stored.

See also

util_env_replace, util_env_free, util_env_find, util_env_create

util_get_current_gmt (declared in libproxy/util.h)

The util_get_current_gmt function obtains the current time, represented in terms of GMT (Greenwich Mean Time).

Syntax

#include <libproxy/util.h>
time_t util_get_current_gmt(void);

Returns

the current GMT

Parameters

No parameter is required.

See also

util_make_local

util_get_int_from_aux_file (declared in libproxy/cutil.h)

The util_get_int_from_aux_file function obtains an integer from a specified file.

Syntax

#include <libproxy/cutil.h>
int util_get_int_from_file(char *root, char *name);

Returns

an integer from the file.

Parameters

char *root is the name of the directory containing the file to be read.

char *name is the name of the file to be read.

See also

util_get_long_from_aux_file, util_get_string_from_aux_file, util_get_int_from_file, util_get_long_from_file, util_get_string_from_file, util_put_int_to_file, util_put_long_to_file, uutil_put_string_to_aux_file, util_put_string_to_file

util_get_long_from_aux_file (declared in libproxy/cutil.h)

The util_get_long_from_file function obtains a long from a specified file.

Syntax

#include <libproxy/cutil.h>
long util_get_long_from_file(char *root,char *name);

Returns

a long integer from the file.

Parameters

char *root is the name of the directory containing the file to be read.

char *name is the name of the file to be read.

See also

util_get_int_from_aux_file, util_get_string_from_aux_file, util_get_int_from_file, util_get_long_from_file, util_get_string_from_file, util_put_int_to_file, util_put_long_to_file, uutil_put_string_to_aux_file, util_put_string_to_file

util_get_string_from_aux_file (declared in libproxy/cutil.h)

The util_get_string_from_aux_file function obtains a single line of text from a specified file and returns it as a string.

Syntax

#include <libproxy/cutil.h>
char *util_get_string_from_file(char *root, char *name, char *buf, int maxsize);

Returns

a string containing the next line from the file.

Parameters

char *root is the name of the directory containing the file to be read.

char *name is the name of the file to be read.

char *buf is the string to use as the file buffer.

int maxsize is the maximum size for the file buffer.

See also

util_get_int_from_aux_file, util_get_long_from_aux_file, util_get_int_from_file, util_get_long_from_file, util_get_string_from_file, util_put_int_to_file, util_put_long_to_file, uutil_put_string_to_aux_file, util_put_string_to_file

util_get_int_from_file (declared in libproxy/cutil.h)

The util_get_int_from_file function obtains an integer from a specified file.

Syntax

#include <libproxy/cutil.h>
int util_get_int_from_file(char *filename);

Returns

• an integer from the file.
• -1 if no value was obtained from the file.

Parameters

char *filename is the name of the file to be read.

See also

util_get_long_from_file, util_get_string_from_file, util_put_int_to_file, util_put_long_to_file, util_put_string_to_file

util_getline (declared in base/util.h)

The util_getline function scans the specified buffer to find an LF- or CRLF-terminated string. The function stores the string in another specified buffer, and NULL-terminates it. Finally, the function returns a value that signals whether the operation stored anything in the buffer or encountered an error and whether it reached the end of the file.

Use this function to scan lines out of a text file, such as a configuration file.

Syntax

#include <base/util.h>
int util_getline(filebuf *buf, int lineno, int maxlen, char *l);

Returns

• 0 if the scan was successful, with the scanned line (less its terminator) in l
• 1 if the scan reached an end of file, with the scanned line (less its terminator) in l
• -1 if the scan resulted in an error, with the error description in l

Parameters

filebuf *buf is the buffer to be scanned.

int lineno is used for error diagnostics to include the line number in the error message. The caller is responsible for making sure the line number is accurate.

int maxlen is the maximum number of characters that can be written into l.

char *l is the buffer into which to store the string. The user is responsible for allocating and deallocating l.

See also

util_can_exec, util_env_create, util_host name

util_get_long_from_file (declared in libproxy/cutil.h)

The util_get_long_from_file function obtains a long integer from a specified file.

Syntax

#include <libproxy/cutil.h>
long util_get_long_from_file(char *filename);

Returns

• a long integer from the file.
• -1 if no value was obtained from the file.

Parameters

char *file is the name of the file to be read.

See also

util_get_int_from_file, util_get_string_from_file, util_put_int_to_file, util_put_long_to_file, util_put_string_to_file

util_get_string_from_file (declared in libproxy/cutil.h)

The util_get_string_from_file function obtains a single line of text from a specified file and returns it as a string.

Syntax

#include <libproxy/cutil.h>
char *util_get_string_from_file(char *filename, char *buf, int maxsize);

Returns

• a string containing the next line from the file.
• NULL if no string was obtained.

Parameters

char *file is the name of the file to be read.

char *buf is the string to use as the file buffer.

int maxsize is the maximum size for the file buffer.

See also

util_get_int_from_file, util_get_long_from_file, util_put_int_to_file, util_put_long_to_file, util_put_string_to_file

util_grab_lock (declared in libproxy/cutil.h)

The util_grab_lock function is for use on systems that do not provide reliable flock( ) or lockf( ) functions. It creates a lock file by using the O_EXCL flag for the open( ) system call to make the open fail if there is already a lock file created by another process.

---

Note	This mechanism is resource intensive and should not be used for locking at a rate of more than once a second.

---

Syntax

#include <libproxy/cutil.h>
int util_grab_lock(char *lck, int key, int retries, int break_after_retry);

Returns

• nonzero if the operation succeeded
• 0 if the operation failed

Parameters

char *lck is the absolute path to the lock file.

int key is the process ID (pid) to use as the key.

int retries is the maximum number of retries before abandoning the lock attempt.

int break_after_retry signals (by a nonzero value) that if all retries have failed, remove the old lock file and retry again.

See also

util_release_lock

util_host name (declared in base/util.h)

The util_host name function retrieves the local host name and returns it as a string. If the function cannot find a fully qualified domain name, it returns NULL. You can reallocate or free this string. Use this function to determine the name of the system you are on.

Syntax

#include <base/util.h>}
char *util_host name(void);

Returns

• If a fully qualified domain name was found, a string containing that name
• NULL if the fully qualified domain name was not found

Parameters

No parameter is required.

See also

util_can_exec, util_env_create, util_getline

util_is_mozilla (declared in base/util.h)

The util_is_mozilla function checks whether a specified user-agent is a Netscape browser of at least a specified revision level, returning a 1 if it is and 0 otherwise. The function uses strings to specify the revision level to avoid ambiguities like 1.56 > 1.5.

Syntax

#include <base/util.h>
int util_is_mozilla(char *ua, char *major, char *minor);

Returns

• 1 if the user-agent is a Netscape browser
• 0 if the user-agent is not a Netscape browser

Parameters

char *ua is the user-agent.

char *major is the major release number (to the left of the decimal point).

char *minor is the minor release number (to the right of the decimal point).

Example

See the example under shexp_cmp

See also

util_is_url, util_later_than

util_is_url (declared in base/util.h)

The util_is_url function checks whether a string is a URL, returning 1 if it is and 0 otherwise.

Syntax

#include <base/util.h>
int util_is_url(char *url);

Returns

• 1 if the string specified by url is a URL
• 0 if the string specified by url is not a URL

Parameters

char *url is the string to be examined.

See also

util_is_mozilla, util_later_than

util_itoa (declared in base/util.h)

The util_itoa function converts a specified integer to a string and returns the length of the string. Use this function to create a textual representation of a number.

Syntax

#include <base/util.h>
int util_itoa(int i, char *a);

Returns

The length of the string created in a

Parameters

int i is the integer to be converted.

char *a is the ASCII string that represents the value. The user is responsible for the allocation and deallocation of a, which should be at least 32 bytes long.

See also

util_sh_escape

util_later_than (declared in base/util.h)

The util_later_than function compares the date specified in a time structure against a date specified in a string. If the date in the string is later than or equal to the one in the time structure, the function returns 1. Use this function to handle RFC 822, 850, and ctime formats.

Syntax

#include <base/util.h>
int util_later_than(struct tm *lms, char *ims);

Returns

• 1 if the date represented by ims is the same as or later than that represented by the lms
• 0 if the date represented by ims is earlier than that represented by the lms

Parameters

tm *lms is the time structure containing a date.

char *ims is the string containing a date.

See also

util_is_mozilla, util_is_url, util_itoa

util_make_filename (declared in libproxy/cutil.h)

The util_make_filename function concatenates a directory name and a filename into a newly created string. This can be handy when you are dealing with a number of files that all go to the same directory.

Syntax

#include <libproxy/cutil.h>
char *util_make_filename(char *root, char *name);

Returns

A new string containing the directory name concatenated with the filename.

Parameters

char *root is a string containing the directory name.

char *name is a string containing the filename.

See also

util_make_lockname

util_make_gmt (declared in libproxy/util.h)

The util_make_gmt function converts a given local time to GMT (Greenwich Mean Time), or obtains the current GMT.

Syntax

#include <libproxy/util.h>
time_t util_make_gmt(time_t t);

Returns

• the GMT equivalent to the local time t, if t is not 0
• the current GMT if t is 0

Parameters

time_t t is a time.

See also

util_make_local, util_get_current_gmt

util_make_local (declared in libproxy/util.h)

The util_make_local function converts a given GMT to local time.

Syntax

#include <libproxy/util.h>
time_t util_make_local(time_t t);

Returns

the local equivalent to the GMT t

Parameters

time_t t is a time.

See also

util_make_gmt, util_get_current_gmt

util_make_lockname (declared in libproxy/cutil.h)

The util_make_lockname function concatenates a filename and a lock suffix into a newly created string.

Syntax

#include <libproxy/cutil.h>
char *util_make_lockname(char *fn);

Returns

A new string containing the filename concatenated with the lock suffix.

Parameters

char *fn is a string containing the filename.

See also

util_make_filename

util_make_printable (declared in libproxy/cutil.h)

The util_make_printable function copies the contents of a binary buffer into a printable buffer. A binary buffer may contain any characters, while a printable buffer must contain only printable characters.

Syntax

#include <libproxy/cutil.h>
void util_make_printable(unsigned char *b, int blen, char *p, int plen);

Returns

void

Parameters

char *b is a binary buffer.

int blen is the length of buffer b.

char *p is a printable buffer of length plen+1 into which the contents of buffer b are copied. The only characters copies are letters, digits, and punctuation characters. No control characters, and not even spaces, are copies.

int plen is the length of buffer b up to, but not including, a terminating NULL.

util_move_dir (declared in libproxy/util.h)

The util_move_dir function moves a directory, preserving permissions, creation times, and last-access times. It attempts to do this by renaming, but if that fails (for example, if the source and destination are on two different file systems), it copies the directory.

Syntax

#include <libproxy/util.h>
int util_move_dir (char *src, char *dst);

Returns

• 0 if the move failed
• nonzero if the move succeeded

Parameters

char *src is the fully qualified name of the source directory.

char *dst is the fully qualified name of the destination directory.

See also

util_move_file

util_move_file (declared in libproxy/util.h)

The util_move_dir function moves a file, preserving permissions, creation time, and last-access time. It attempts to do this by renaming, but if that fails (for example, if the source and destination are on two different file systems), it copies the file.

Syntax

#include <libproxy/util.h>
int util_move_file (char *src, char *dst);

Returns

• 0 if the move failed
• nonzero if the move succeeded

Parameters

char *src is the fully qualified name of the source file.

char *dst is the fully qualified name of the destination file.

See also

util_move_dir

util_parse_http_time (declared in libproxy/util.h)

The util_parse_http_time function converts a given HTTP time string to time_t format.

Syntax

#include <libproxy/util.h>
time_t util_parse_http_time(char *date_string);

Returns

the time_t equivalent to the GMT t

Parameters

time_t t is a time.

See also

util_make_gmt, util_get_current_gmt

util_put_int_to_file (declared in libproxy/cutil.h)

The util_put_int_to_file function writes a single line containing an integer to a specified file.

Syntax

#include <libproxy/cutil.h>
int util_put_int_to_file(char *filename, int i);

Returns

• nonzero if the operation succeeded
• 0 if the operation failed

Parameters

char *file is the name of the file to be written.

int i is the integer to write.

See also

util_get_int_from_file, util_get_long_from_file, util_put_long_to_file, util_put_string_to_file

util_put_long_to_file (declared in libproxy/cutil.h)

The util_put_long_to_file function writes a single line containing a long integer to a specified file.

Syntax

#include <libproxy/cutil.h>
ing util_put_long_to_file(char *filename, long l);

Returns

• nonzero if the operation succeeded
• 0 if the operation failed

Parameters

char *file is the name of the file to be written.

long l is the long integer to write.

See also

util_get_int_from_file, util_get_long_from_file, util_put_int_to_file, util_put_string_to_file

util_put_string_to_aux_file (declared in libproxy/cutil.h)

The util_put_string_to_aux_file function writes a single line containing a string to a file specified by directory name and file name.

Syntax

#include <libproxy/cutil.h>
int util_put_string_to_aux_file(char *root, char *name, char *str);

Returns

• non-zero if the operation succeeded
• 0 if the operation failed

Parameters

char *root is the name of the directory where the file is to be written.

char *name is the name of the file is to be written.

char *str is the string to write.

See also

util_get_int_from_file, util_get_long_from_file, util_put_int_to_file, util_put_long_to_file, util_put_string_to_file

util_put_string_to_file (declared in libproxy/cutil.h)

The util_put_string_to_file function writes a single line containing a string to a specified file.

Syntax

#include <libproxy/cutil.h>
int util_put_string_to_file(char *filename, char *str);

Returns

• nonzero if the operation succeeded
• 0 if the operation failed

Parameters

char *file is the name of the file to be read.

char *str is the string to write.

See also

util_get_int_from_file, util_get_long_from_file, util_put_int_to_file, util_put_long_to_file

util_release_lock (declared in libproxy/cutil.h)

The util_release_lock function releases a lock established by the util_grab_lock function.

Syntax

#include <libproxy/cutil.h>
int util_release_lock(char *lck, int key, int force);

Returns

• nonzero if the operation succeeded
• 0 if the operation failed

Parameters

char *lck is the absolute path to the lock file to be removed.

int key is the process ID (pid) to use as the key.

int force indicates (by a value other than zero) that the lock is to be removed even if the pid in that file does not match the pid of the process making the call to util_release_lock.

See also

util_grab_lock

util_sect_id (declared in libproxy/cutil.h)

The util_sect_id function creates a section ID from the section dim and an index.

Syntax

#include <libproxy/cutil.h>
void util_sect_id(int dim, int idx, char *buf);

Returns

• nonzero if the operation succeeded
• 0 if the operation failed

Parameters

int dim is the section dim.

int idx is the index.

char *buf is the buffer to receive the section ID.

util_sh_escape (declared in base/util.h)

The util_sh_escape function parses a specified string and places a backslash (\) in front of any shell-special characters, returning the resultant string. Use this function to ensure that strings from clients won't cause a shell to do anything unexpected.

Syntax

#include <base/util.h>
char *util_sh_escape(char *s);

Returns

A newly allocated string

Parameters

char *s is the string to be parsed.

See also

util_uri_escape

util_snprintf (declared in base/util.h)

The util_snprintf function formats a specified string, using a specified format, into a specified buffer using the printf-style syntax and performs bounds checking. It returns the number of characters in the formatted buffer.

For more information, see the documentation on the printf function for the run-time library of your compiler.

Syntax

#include <base/util.h>
int util_snprintf(char *s, int n, char *fmt, ...);

Returns

The number of characters formatted into the buffer.

Parameters

char *s is the buffer to receive the formatted string.

int n is the maximum number of bytes allowed to be copied.

char *fmt is the format string. The function handles only %d and %s strings; it does not handle any width or precision strings.

... represents a sequence of parameters for the printf function.

Example

Similar to the example for util_sprintf.

See also

util_sprintf, util_vsnprintf, util_vsprintf

util_sprintf (declared in base/util.h)

The util_sprintf function formats a specified string, using a specified format, into a specified buffer using the printf-style syntax without bounds checking. It returns the number of characters in the formatted buffer.

Because util_sprintf doesn't perform bounds checking, use this function only if you are certain that the string fits the buffer. Otherwise, use the function util_snprintf. For more information, see the documentation on the printf function for the run-time library of your compiler.

Syntax

#include <base/util.h>
int util_sprintf(char *s, char *fmt, ...);

Returns

The number of characters printed.

Parameters

char *s is the buffer to receive the formatted string.

char *fmt is the format string. The function handles only %d and %s strings; it does not handle any width or precision strings.

... represents a sequence of parameters for the printf function.

Example

int brief_log(pblock *pb, Session *sn, Request *rq)
{
char *method = pblock_findval("method", rq->reqpb);
   char *uri = pblock_findval("uri", rq->reqpb);
   char *ip = pblock_findval("ip", sn->client);
   /* Temp vars */
   char *logmsg;
   int len;
   logmsg = (char *)
      MALLOC(strlen(ip) + 1 + strlen(method) + 1
            + strlen(uri) + 1 + 1);
   len = util_sprintf(logmsg, "%s %s %s\n", ip, method, uri);
   /* The atomic version uses locking to prevent interference */
   system_fwrite_atomic(logfd, logmsg, len);
   FREE(logmsg);
   return REQ_PROCEED;
}

See also

util_snprintf, util_vsnprintf, util_vsprintf

util_strcasecmp (declared in base/systems.h)

The util_strcasecmp function performs a comparison of two alphanumeric strings and returns a -1, 0, or 1 to signal which is larger or that they are identical. The function's comparison is not case-sensitive.

Syntax

#include <base/systems.h>
int util_strcasecmp(const char *s1, const char *s2);

Returns

• 1 if s1 is greater than s2
• 0 if s1 is equal to s2
• -1 if s1 is less than s2

Parameters

char *s1 is the first string.

char *s2 is the second string.

See also

util_strncasecmp

util_strncasecmp (declared in base/systems.h)

The util_strncasecmp function performs a comparison of the first n characters in the alphanumeric strings and returns a -1, 0, or 1 to signal which is larger or that they are identical. The function's comparison is not case-sensitive.

Syntax

#include <base/systems.h>
int util_strncasecmp(const char *s1, const char *s2, int n);

Returns

• 1 if s1 is greater than s2
• 0 if s1 is equal to s2
• -1 if s1 is less than s2

Parameters

char *s1 is the first string.

char *s2 is the second string.

int n is the number of initial characters to compare.

See also

util_strcasecmp

util_uri_check (declared in libproxy/util.h)

The util_uri_check function checks that a URI has a format conforming to the standard.

At present, the only URI it checks for is a URL. The standard format for a URL is

protocol://user:password@host:port/url-path

where user:password, :password. :port, or /url-path can be omitted.

Syntax

#include <libproxy/util.h>
int util_uri_check (char *uri);

Returns

• 0 if the URI does not have the proper form.
• nonzero if the URI has the proper form.

Parameters

char *uri is the URI to be tested.

util_uri_escape (declared in base/util.h)

The util_uri_escape function converts any special characters in a specified string into the URI format, and returns the escaped string. Use util_uri_escape before sending the URI back to the client.

Syntax

#include <base/util.h>
char *util_uri_escape(char *d, char *s);

Returns

The string (possibly newly allocated) with escaped characters replaced.

Parameters

char *d is a string. If d is not NULL, the function copies the formatted string into d and returns it. If d is NULL, the function allocates a properly sized string and copies the formatted special characters into the new string, then returns it.

The util_uri_escape function does not check bounds for the parameter d. Therefore, d should be at least three times as large as s.

char *s is the string containing the unescaped form of the URI.

See also

util_uri_is_evil, util_uri_parse, util_uri_unescape

util_uri_is_evil (declared in base/util.h)

The util_uri_is_evil function checks a specified URI and returns 1 if it contains ../ or //. Use this function to make sure that a URI given by a client won't do anything unexpected.

Syntax

#include <base/util.h>
int util_uri_is_evil(char *t);

Returns

• 1 if the URI contains ../ or //
• 0 if the URI does not contain ../ or //

Parameters

char *t is the URI to be checked.

See also

util_uri_escape, util_uri_parse

util_uri_parse (declared in base/util.h)

The util_uri_parse function removes /../, /./, and // in a specified URI. You can use this function to convert a URI's bad sequences into valid ones. First use the function util_uri_is_evil to determine whether the function has a bad sequence.

Syntax

#include <base/util.h>
void util_uri_parse(char *uri);

Returns

void

Parameters

char *uri is the URI to be converted.

See also

util_uri_is_evil, util_uri_unescape

util_uri_unescape (declared in base/util.h)

The util_uri_unescape function converts the encoded characters of a specified URI into special characters in place.

Syntax

#include <base/util.h>
void util_uri_unescape(char *uri);

Returns

void

Parameters

char *uri is the URI to be converted.

See also

util_uri_escape, util_uri_is_evil, util_uri_parse

util_url_cmp (declared in libproxy/util.h)

The util_url_cmp function compares two URLs. It is analogous to the strcmp( ) library function of C.

Syntax

#include <libproxy/util.h>
int util_url_cmp (char *s1, char *s2);

Returns

• -1 if the first URL, s1, is less than the second, s2
• 0 if they are identical
• 1 if the first URL, s1, is greater than the second, s2

Parameters

char *s1 is the first URL to be tested.

char *s2 is the second URL to be tested.

See also

util_url_fix_host name, util_uri_check

util_url_fix_host name (declared in libproxy/util.h)

The util_url_fix_host name function converts the host name in a URL to lowercase and removes redundant port numbers.

Syntax

#include <libproxy/util.h>
void util_url_fix_host name(char *url);

Returns

void (but changes the value of its parameter string)

The protocol specifier and the host name in the parameter string are changed to lowercase. The function also removes redundant port numbers, such as 80 for HTTP, 70 for gopher, and 21 for FTP.

Parameters

char *url is the URL to be converted.

See also

util_url_cmp, util_uri_check.

util_url_has_FQDN (declared in libproxy/util.h)

The util_url_has_FQDN function returns a value to indicate whether a specified URL references a fully qualified domain name.

Syntax

#include <libproxy/util.h>
int util_url_has_FQDN(char *url);

Returns

• 1 if the URL has a fully qualified domain name
• 0 if the URL does not have a fully qualified domain name

Parameters

char *url is the URL to be examined.

util_vsnprintf (declared in base/util.h)

The util_vsnprintf function formats a specified string, using a specified format, into a specified buffer using the vprintf-style syntax and performs bounds checking. It returns the number of characters in the formatted buffer.

For more information, see the documentation on the printf function for the run-time library of your compiler.

Use this function if you want a vsprintf syntax that takes a standard arg format. For more information, see the documentation on the vsprintf function for the run-time library of your compiler.

Syntax

#include <base/util.h>
int util_vsnprintf(char *s, int n, register char *fmt, va_list args);

Returns

The number of characters printed

Parameters

char *s is the buffer to receive the formatted string.

int n is the maximum number of bytes allowed to be copied.

register char *fmt is the format string. The function handles only %d and %s strings; it does not handle any width or precision strings.

va_list args is an STD arg variable obtained from a previous call to va_start.

See also   

util_sprintf, util_vsprintf

util_vsprintf (declared in base/util.h)

The util_vsprintf function formats a specified string, using a specified format, into a specified buffer using the vprintf-style syntax without bounds checking. It returns the number of characters in the formatted buffer.

For more information, see the documentation on the printf function for the run-time library of your compiler.

Use this function if you want a vsprintf syntax that takes a standard arg format. For more information, see the documentation on the vsprintf function for the runtime library of your compiler.

Syntax

#include <base/util.h>
int util_vsprintf(char *s, register char *fmt, va_list args);

Returns

The number of characters printed

Parameters

char *s is the buffer to receive the formatted string.

register char *fmt is the format string. The function handles only %d and %s strings; it does not handle any width or precision strings.

va_list args is an STD arg variable obtained from a previous call to va_start.

See also

util_snprintf, util_vsnprintf