Table of Contents | Previous
| Next
| Index
| Bookshelf
NSAPI Programmer's Guide for iPlanet Web Server
This chapter lists all the public C functions and macros of the Netscape Server Applications Programming Interface (NSAPI) in alphabetic order. These are the functions you use when writing your own Server Application Functions (SAFs). For information on the built-in SAFs, see Chapter 3, "Predefined SAFs and the Request Handling Process."
Each function provides the name, syntax, parameters, return value, a description of what the function does, and sometimes an example of its use and a list of related functions.
For more information on data structures, see Appendix A, "Data Structure Reference," and also look in the nsapi.h header file in the include directory in the build for iPlanet Web Server 4.x.
For an alphabetical list of function names, see Appendix H, "Alphabetical List of NSAPI Functions and Macros."
The CALLOC macro is a platform-independent substitute for the C library routine calloc. It allocates num*size bytes from the request's memory pool. If pooled memory has been disabled in the configuration file (with the pool-init built-in SAF), PERM_CALLOC and CALLOC both obtain their memory from the system heap.
void *CALLOC(int num, int size)
A void pointer to a block of memory.
int num is the number of elements to allocate.
int size is the size in bytes of each element.
/* Allocate space for an array of 100 char pointers */
char *name;
name = (char *) CALLOC(100, sizeof(char *));
FREE, REALLOC, STRDUP, PERM_MALLOC, PERM_FREE, PERM_REALLOC,
PERM_STRDUP
The cinfo_find() function uses the MIME types information to find the type, encoding, and/or language based on the extension(s) of the Universal Resource Identifier (URI) or local file name. Use this information to send headers (rq->srvhdrs) to the client indicating the content-type, content-encoding, and content-language of the data it will be receiving from the server.
The name used is everything after the last slash (/) or the whole string if no slash is found. File name extensions are not case-sensitive. The name may contain multiple extensions separated by period (.) to indicate type, encoding, or language. For example, the URI a/b/filename.jp.txt.zip could represent a Japanese language, text/plain type, zip encoded file.
cinfo *cinfo_find(char *uri);
A pointer to a newly allocated cinfo structure if content info was found or
NULL if no content was found
The cinfo structure that is allocated and returned contains pointers to the
content-type, content-encoding, and content-language, if found. Each is a
pointer into static data in the types database, or NULL if not found. Do not free
these pointers. You should free the cinfo structure when you are done using
it.
char *uri is a Universal Resource Identifier (URI) or local file name. Multiple
file name extensions should be separated by periods (.).
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 prevent interference between two threads of execution.
CONDVAR condvar_init(CRITICAL id);
A newly allocated condition variable (CONDVAR).
CRITICAL id is a critical-section variable.
condvar_notify, condvar_terminate, condvar_wait, crit_init,
crit_enter, crit_exit, crit_terminate.
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.
void condvar_notify(CONDVAR cv);
void
CONDVAR cv is a condition variable.
condvar_init, condvar_terminate, condvar_wait, crit_init,
crit_enter, crit_exit, crit_terminate.
The condvar_terminate function is a critical-section function that frees a condition variable. Use this function to free a previously allocated condition variable.
Terminating a condition variable that is in use can lead to unpredictable results.
void condvar_terminate(CONDVAR cv);
void
CONDVAR cv is a condition variable.
condvar_init, condvar_notify, condvar_wait, crit_init,
crit_enter, crit_exit, crit_terminate.
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.
void condvar_wait(CONDVAR cv);
void
CONDVAR cv is a condition variable.
condvar_init, condvar_notify, condvar_terminate, crit_init,
crit_enter, crit_exit, crit_terminate.
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.
void crit_enter(CRITICAL crvar);
void
CRITICAL crvar is a critical-section variable.
crit_init, crit_exit, crit_terminate.
Critical-section function that surrenders ownership of a critical section. Use this function to surrender ownership of a critical section. If another thread is blocked waiting for the section, the block will be removed and the waiting thread will be given ownership of the section.
void crit_exit(CRITICAL crvar);
void
CRITICAL crvar is a critical-section variable.
crit_init, crit_enter, crit_terminate.
Critical-section function that creates and returns a new critical-section variable (a variable of type CRITICAL). Use this function to obtain a new instance of a variable of type CRITICAL (a critical-section variable) to be used in managing the prevention of interference between two threads of execution. At the time of its creation, no thread owns the critical section.
Threads must not own or be waiting for the critical section when
crit_terminate is called.
CRITICAL crit_init(void);
A newly allocated critical-section variable (CRITICAL)
none.
crit_enter, crit_exit, crit_terminate.
Critical-section function that removes a previously-allocated critical-section variable (a variable of type CRITICAL). Use this function to release a critical-section variable previously obtained by a call to crit_init.
void crit_terminate(CRITICAL crvar);
void
CRITICAL crvar is a critical-section variable.
crit_init, crit_enter, crit_exit.
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.
void daemon_atrestart(void (*fn)(void *), void *data);
void
void (* fn) (void *) is the callback function.
void *data is the parameter passed to the callback function when the server
is restarted.
/* Register the brief_terminate function, passing it NULL */
/* to close *a log file when the server is */
/* restarted or shutdown. */
daemon_atrestart(log_close, NULL);
NSAPI_PUBLIC void log_close(void *parameter)
{
system_fclose(global_logfd);
}
The filebuf_buf2sd function sends a file buffer to a socket (descriptor) and returns the number of bytes sent.
Use this function to send the contents of an entire file to the client.
int filebuf_buf2sd(filebuf *buf, SYS_NETFD sd);
The number of bytes sent to the socket, if successful, or the constant IO_ERROR
if the file buffer could not be sent
filebuf *buf is the file buffer which must already have been opened.
SYS_NETFD sd is the platform-independent socket descriptor. Normally this will
be obtained from the csd (client socket descriptor) field of the sn (Session)
structure.
if (filebuf_buf2sd(buf, sn->csd) == IO_ERROR)
return(REQ_EXIT);
filebuf_close, filebuf_open, filebuf_open_nostat, filebuf_getc.
The filebuf_close function deallocates a file buffer and closes its associated file.
Generally, use filebuf_open first to open a file buffer, and then filebuf_getc to access the information in the file. After you have finished using the file buffer, use filebuf_close to close it.
void filebuf_close(filebuf *buf);
void
filebuf *buf is the file buffer previously opened with filebuf_open.
filebuf_close(buf);
filebuf_open, filebuf_open_nostat, filebuf_buf2sd, filebuf_getc
The filebuf_getc function retrieves a character from the current file position and returns it as an integer. It then increments the current file position.
Use filebuf_getc to sequentially read characters from a buffered file.
filebuf_getc(filebuf b);
An integer containing the character retrieved, or the constant IO_EOF or
IO_ERROR upon an end of file or error.
filebuf b is the name of the file buffer.
filebuf_close, filebuf_buf2sd, filebuf_open,
filebuf_open_nostat
The filebuf_open function opens a new file buffer for a previously opened file. It returns a new buffer structure. Buffered files provide more efficient file access by guaranteeing the use of buffered file I/O in environments where it is not supported by the operating system.
filebuf *filebuf_open(SYS_FILE fd, int sz);
A pointer to a new buffer structure to hold the data, if successful or NULL if no
buffer could be opened.
SYS_FILE fd is the platform-independent file descriptor of the file which has
already been opened.
int sz is the size, in bytes, to be used for the buffer.
filebuf *buf = filebuf_open(fd, FILE_BUFFERSIZE);
if (!buf) {
system_fclose(fd);
}
filebuf_getc, filebuf_buf2sd, filebuf_close,
filebuf_open_nostat
The filebuf_open_nostat function opens a new file buffer for a previously opened file. It returns a new buffer structure. Buffered files provide more efficient file access by guaranteeing the use of buffered file I/O in environments where it is not supported by the operating system.
This function is the same filebuf_open, but is more efficient, since it does not need to call the request_stat_path function. It requires that the stat information be passed in.
filebuf* filebuf_open_nostat(SYS_FILE fd, int sz,
struct stat *finfo);
A pointer to a new buffer structure to hold the data, if successful or NULL if no
buffer could be opened.
SYS_FILE fd is the platform-independent file descriptor of the file which has
already been opened.
int sz is the size, in bytes, to be used for the buffer.
struct stat *finfo is the file information of the file. Before calling the
filebuf_open_nostat function, you must call the request_stat_path
function to retrieve the file information.
filebuf *buf = filebuf_open_nostat(fd, FILE_BUFFERSIZE, &finfo);
if (!buf) {
system_fclose(fd);
}
filebuf_close, filebuf_open, filebuf_getc, filebuf_buf2sd
The FREE macro is a platform-independent substitute for the C library routine free. It deallocates the space previously allocated by MALLOC, CALLOC, or STRDUP from the request's memory pool.
FREE(void *ptr);
void
void *ptr is a (void *) pointer to a block of memory. If the pointer is not
one created by MALLOC, CALLOC, or STRDUP, the behavior is undefined.
char *name;
name = (char *) MALLOC(256);
...
FREE(name);
MALLOC, CALLOC, REALLOC, STRDUP, PERM_MALLOC, PERM_FREE,
PERM_REALLOC, PERM_STRDUP
The func_exec function executes the function named by the fn entry in a specified pblock. If the function name is not found, it logs the error and returns REQ_ABORTED.
You can use this function to execute a built-in server application function (SAF) by identifying it in the pblock.
int func_exec(pblock *pb, Session *sn, Request *rq);
The value returned by the executed function or the constant REQ_ABORTED if no
function was executed.
pblock pb is the pblock containing the function name (fn) and parameters.
Session *sn is the Session.
Request *rq is the Request.
The Session and Request parameters are the same as the ones passed into your
SAF.
log_error
The func_find function returns a pointer to the function specified by name. If the function does not exist, it returns NULL.
FuncPtr func_find(char *name);
A pointer to the chosen function, suitable for dereferencing or NULL if the
function could not be found.
char *name is the name of the function.
/* 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);
func_exec
The log_error function creates an entry in an error log, recording the date, the severity, and a specified text.
int log_error(int degree, char *func, Session *sn, Request *rq,
char *fmt, ...);
0 if the log entry was created or -1 if the log entry was not created.
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 has occurred.
Session *sn is the Session.
Request *rq is the Request.
The Session and Request parameters are the same as the ones passed into your
SAF.
char *fmt specifies the format for the printf function that delivers the
message.
... represents a sequence of parameters for the printf function.
log_error(LOG_WARN, "send-file", sn, rq,
"error opening buffer from %s (%s)"), path,
system_errmsg(fd));
func_exec
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.
void magnus_atrestart(void (*fn)(void *), void *data);
void
void (* fn) (void *) is the callback function.
void *data is the parameter passed to the callback function when the server
is restarted.
/* Close log file when server is restarted */
magnus_atrestart(brief_terminate, NULL);
return REQPROCEED;
The MALLOC macro is a platform-independent substitute for the C library routine malloc. It normally allocates from the request's memory pool. If pooled memory has been disabled in the configuration file (with the pool-init built-in SAF), PERM_MALLOC and MALLOC both obtain their memory from the system heap.
void *MALLOC(int size)
A void pointer to a block of memory.
int size is the number of bytes to allocate.
/* Allocate 256 bytes for a name */
char *name;
name = (char *) MALLOC(256);
FREE, CALLOC, REALLOC, STRDUP, PERM_MALLOC, PERM_FREE,
PERM_CALLOC, PERM_REALLOC, PERM_STRDUP
The net_ip2host function transforms a textual IP address into a fully-qualified domain name and returns it.
char *net_ip2host(char *ip, int verify);
A new string containing the fully-qualified domain name, if the transformation
was accomplished or NULL if the transformation was not accomplished.
char *ip is the IP (Internet Protocol) address as a character string in dotted-
decimal notation: nnn.nnn.nnn.nnn
int verify, if non-zero, specifies that the function should verify the fully-
qualified domain name. Though this requires an extra query, you should use it
when checking access control.
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.
int net_read (SYS_NETFD sd, char *buf, int sz, int timeout);
The number of bytes read, which will not exceed the maximum size, sz. A
negative value is returned 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.
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.
net_write
The net_write function writes a specified number of bytes to a specified socket from a specified buffer. It returns the number of bytes written.
int net_write(SYS_NETFD sd, char *buf, int sz);
The number of bytes written, which may be less than the requested size if an
error occurred.
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.
if (net_write(sn->csd, FIRSTMSG, strlen(FIRSTMSG)) == IO_ERROR)
return REQ_EXIT;
net_read
The netbuf_buf2sd function sends a buffer to a socket. You can use this function to send data from IPC pipes to the client.
int netbuf_buf2sd(netbuf *buf, SYS_NETFD sd, int len);
The number of bytes transferred to the socket, if successful or the constant
IO_ERROR if unsuccessful
netbuf *buf is the buffer to send.
SYS_NETFD sd is the platform-independent identifier of the socket.
int len is the length of the buffer.
netbuf_close, netbuf_getc, netbuf_grab, netbuf_open
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.
void netbuf_close(netbuf *buf);
void
netbuf *buf is the buffer to close.
netbuf_buf2sd, netbuf_getc, netbuf_grab, netbuf_open
The netbuf_getc function retrieves a character from the cursor position of the network buffer specified by b.
netbuf_getc(netbuf b);
The integer representing the character, if one was retrieved or the constant
IO_EOF or IO_ERROR, for end of file or error
netbuf b is the buffer from which to retrieve one character.
netbuf_buf2sd, netbuf_close, netbuf_grab, netbuf_open
The netbuf_grab function reads sz number of bytes from the network buffer's (buf) socket into the network buffer. If the buffer is not large enough it is resized. The data can be retrieved from buf->inbuf on success.
This function is used by the function netbuf_buf2sd.
int netbuf_grab(netbuf *buf, int sz);
The number of bytes actually read (between 1 and sz), if the operation was
successful or the constant IO_EOF or IO_ERROR, for end of file or error
netbuf *buf is the buffer to read into.
int sz is the number of bytes to read.
netbuf_buf2sd, netbuf_close, netbuf_getc, netbuf_open
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.
netbuf* netbuf_open(SYS_NETFD sd, int sz);
A pointer to a new netbuf structure (network buffer)
SYS_NETFD sd is the platform-independent identifier of the socket.
int sz is the number of characters to allocate for the network buffer.
netbuf_buf2sd, netbuf_close, netbuf_getc, netbuf_grab
The param_create function creates a pb_param structure containing a specified name and value. The name and value are copied. Use this function to prepare a pb_param structure to be used in calls to pblock routines such as pblock_pinsert.
pb_param *param_create(char *name, char *value);
A pointer to a new pb_param structure.
char *name is the string containing the name.
char *value is the string containing the value.
pb_param *newpp = param_create("content-type","text/plain");
pblock_pinsert(newpp, rq->srvhdrs);
param_free, pblock_pinsert, pblock_remove
The param_free function frees the pb_param structure specified by pp and its associated structures. Use the param_free function to dispose a pb_param after removing it from a pblock with pblock_remove.
int param_free(pb_param *pp);
1 if the parameter was freed or 0 if the parameter was NULL.
pb_param *pp is the name-value pair stored in a pblock.
if (param_free(pblock_remove("content-type", rq-srvhdrs)))
return; /* we removed it */
param_create, pblock_pinsert, pblock_remove
The pblock_copy function copies the entries of the source pblock and adds them into the destination pblock. Any previous entries in the destination pblock are left intact.
void pblock_copy(pblock *src, pblock *dst);
void
pblock *src is the source pblock.
pblock *dst is the destination pblock.
Names and values are newly allocated so that the original pblock may be
freed, or the new pblock changed without affecting the original pblock.
pblock_create, pblock_dup, pblock_free, pblock_find,
pblock_findval, pblock_remove, pblock_nvinsert
The pblock_create function creates a new pblock. The pblock maintains an internal hash table for fast name-value pair lookups.
pblock *pblock_create(int n);
A pointer to a newly allocated pblock.
int n is the size of the hash table (number of name-value pairs) for the
pblock.
pblock_copy, pblock_dup, pblock_find, pblock_findval,
pblock_free, pblock_nvinsert, pblock_remove
The pblock_dup function duplicates a pblock. It is equivalent to a sequence of pblock_create and pblock_copy.
pblock *pblock_dup(pblock *src);
A pointer to a newly allocated pblock.
pblock *src is the source pblock.
pblock_create, pblock_find, pblock_findval, pblock_free,
pblock_find, pblock_remove, pblock_nvinsert
The pblock_find function finds a specified name-value pair entry in a pblock, and returns the pb_param structure. If you only want the value associated with the name, use the pblock_findval function.
This function is implemented as a macro.
pb_param *pblock_find(char *name, pblock *pb);
A pointer to the pb_param structure, if one was found or NULL if name was not
found.
char *name is the name of a name-value pair.
pblock *pb is the pblock to be searched.
pblock_copy, pblock_dup, pblock_findval, pblock_free,
pblock_nvinsert, pblock_remove
The pblock_findval function finds the value of a specified name in a pblock. If you just want the pb_param structure of the pblock, use the pblock_find function.
The pointer returned is a pointer into the pblock. Do not FREE it. If you want to modify it, do a STRDUP and modify the copy.
char *pblock_findval(char *name, pblock *pb);
A string containing the value associated with the name or NULL if no match
was found
char *name is the name of a name-value pair.
pblock *pb is the pblock to be searched.
see pblock_nvinsert.
pblock_create, pblock_copy, pblock_find, pblock_free,
pblock_nvinsert, pblock_remove, request_header
The pblock_free function frees a specified pblock and any entries inside it. If you want to save a variable in the pblock, remove the variable using the function pblock_remove and save the resulting pointer.
void pblock_free(pblock *pb);
void
pblock *pb is the pblock to be freed.
pblock_copy, pblock_create, pblock_dup, pblock_find,
pblock_findval, pblock_nvinsert, pblock_remove
The pblock_nninsert function creates a new entry with a given name and a numeric value in the specified pblock. The numeric value is first converted into a string. The name and value parameters are copied.
pb_param *pblock_nninsert(char *name, int value, pblock *pb);
A pointer to the new pb_param structure.
char *name is the name of the new entry.
int value is the numeric value being inserted into the pblock. This
parameter must 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 pblock into which the insertion occurs.
pblock_copy, pblock_create, pblock_find, pblock_free,
pblock_nvinsert, pblock_remove, pblock_str2pblock
The pblock_nvinsert function creates a new entry with a given name and character value in the specified pblock. The name and value parameters are copied.
pb_param *pblock_nvinsert(char *name, char *value, pblock *pb);
A pointer to the newly allocated pb_param structure
char *name is the name of the new entry.
char *value is the string value of the new entry.
pblock *pb is the pblock into which the insertion occurs.
pblock_nvinsert("content-type", "text/html", rq->srvhdrs);
pblock_copy, pblock_create, pblock_find, pblock_free,
pblock_nninsert, pblock_remove, pblock_str2pblock
The pblock_pb2env function copies a specified pblock into a specified environment. The function creates one new environment entry for each name-value pair in the pblock. Use this function to send pblock entries to a program that you are going to execute.
char **pblock_pb2env(pblock *pb, char **env);
A pointer to the environment.
pblock *pb is the pblock to be copied.
char **env is the environment into which the pblock is to be copied.
pblock_copy, pblock_create, pblock_find, pblock_free,
pblock_nvinsert, pblock_remove, pblock_str2pblock
The pblock_pblock2str function copies all parameters of a specified pblock into a specified string. The function allocates additional non-heap space for the string if needed.
Use this function to stream the pblock for archival and other purposes.
char *pblock_pblock2str(pblock *pb, char *str);
The new version of the str parameter. If str is NULL, this is a new string;
otherwise it is a reallocated string. In either case, it is allocated from the
request's memory pool.
pblock *pb is the pblock to be copied.
char *str is the string into which the pblock is to be copied. It must have
been allocated by MALLOC or REALLOC, not by PERM_MALLOC or
PERM_REALLOC (which allocate from the system heap).
Each name-value pair in the string is separated from its neighbor pair by a
space and is in the format name="value".
pblock_copy, pblock_create, pblock_find, pblock_free,
pblock_nvinsert, pblock_remove, pblock_str2pblock
The function pblock_pinsert inserts a pb_param structure into a pblock.
void pblock_pinsert(pb_param *pp, pblock *pb);
void
pb_param *pp is the pb_param structure to insert.
pblock *pb is the pblock.
pblock_copy, pblock_create, pblock_find, pblock_free,
pblock_nvinsert, pblock_remove, pblock_str2pblock
The pblock_remove function removes a specified name-value entry from a specified pblock. If you use this function you should eventually call param_free in order to deallocate the memory used by the pb_param structure.
pb_param *pblock_remove(char *name, pblock *pb);
A pointer to the named pb_param structure, if it was found or NULL if the
named pb_param was not found.
char *name is the name of the pb_param to be removed.
pblock *pb is the pblock from which the name-value entry is to be removed.
pblock_copy, pblock_create, pblock_find, pblock_free,
pblock_nvinsert, param_create, param_free
The pblock_str2pblock function scans a string for parameter pairs, adds them to a pblock, and returns the number of parameters added.
int pblock_str2pblock(char *str, pblock *pb);
The number of parameter pairs added to the pblock, if any or -1 if an error
occurred
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 back slashes (\) 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. For example, if pblock_str2pblock
finds "some strings together", the function treats the strings as if they
appeared in name-value pairs as 1="some" 2="strings" 3="together".
pblock *pb is the pblock into which the name-value pairs are stored.
pblock_copy, pblock_create, pblock_find, pblock_free,
pblock_nvinsert, pblock_remove, pblock_pblock2str
The PERM_CALLOC macro is a platform-independent substitute for the C library routine calloc. It allocates num*size bytes of memory that persists after the request that is being processed has been completed. If pooled memory has been disabled in the configuration file (with the pool-init built-in SAF), PERM_CALLOC and CALLOC both obtain their memory from the system heap.
void *PERM_CALLOC(int num, int size)
A void pointer to a block of memory
int num is the number of elements to allocate.
int size is the size in bytes of each element.
/* Allocate 256 bytes for a name */
char **name;
name = (char **) PERM_CALLOC(100, sizeof(char *));
PERM_FREE, PERM_STRDUP, PERM_MALLOC, PERM_REALLOC, MALLOC, FREE,
CALLOC, STRDUP, REALLOC
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, PERM_CALLOC, or PERM_STRDUP. If pooled memory has been disabled in the configuration file (with the pool-init built-in SAF), PERM_FREE and FREE both deallocate memory in the system heap.
PERM_FREE(void *ptr);
void
void *ptr is a (void *) pointer to block of memory. If the pointer is not one
created by PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP, the behavior is
undefined.
char *name;
name = (char *) PERM_MALLOC(256);
...
PERM_FREE(name);
FREE, MALLOC, CALLOC, REALLOC, STRDUP, PERM_MALLOC, PERM_CALLOC,
PERM_REALLOC, PERM_STRDUP
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 is being processed has been completed. If pooled memory has been disabled in the configuration file (with the pool-init built-in SAF), PERM_MALLOC and MALLOC both obtain their memory from the system heap.
void *PERM_MALLOC(int size)
A void pointer to a block of memory
int size is the number of bytes to allocate.
/* Allocate 256 bytes for a name */
char *name;
name = (char *) PERM_MALLOC(256);
PERM_FREE, PERM_STRDUP, PERM_CALLOC, PERM_REALLOC, MALLOC, FREE,
CALLOC, STRDUP, REALLOC
The PERM_REALLOC macro is a platform-independent substitute for the C library routine realloc. It changes the size of a specified memory block that was originally created by MALLOC, CALLOC, or STRDUP. The contents of the object remains unchanged up to the lesser of the old and new sizes. If the new size is larger, the new space is uninitialized.
Calling PERM_REALLOC for a block that was allocated with MALLOC, CALLOC, or
STRDUP will not work.
void *PERM_REALLOC(vod *ptr, int size)
A void pointer to a block of memory
void *ptr a void pointer to a block of memory created by PERM_MALLOC,
PERM_CALLOC, or PERM_STRDUP.
int size is the number of bytes to which the memory block should be
resized.
char *name;
name = (char *) PERM_MALLOC(256);
if (NotBigEnough())
name = (char *) PERM_REALLOC(512);
PERM_MALLOC, PERM_FREE, PERM_CALLOC, PERM_STRDUP, MALLOC, FREE,
STRDUP, CALLOC, REALLOC
The PERM_STRDUP macro is a platform-independent substitute for the C library routine strdup. It creates a new copy of a string in memory that persists after the request that is being processed has been completed. If pooled memory has been disabled in the configuration file (with the pool-init built-in SAF), PERM_STRDUP and STRDUP both obtain their memory from the system heap.
The PERM_STRDUP routine is functionally equivalent to
newstr = (char *) PERM_MALLOC(strlen(str) + 1);
strcpy(newstr, str);
A string created with PERM_STRDUP should be disposed with PERM_FREE.
char *PERM_STRDUP(char *ptr);
A pointer to the new string
char *ptr is a pointer to a string.
PERM_MALLOC, PERM_FREE, PERM_CALLOC, PERM_REALLOC, MALLOC, FREE,
STRDUP, CALLOC, REALLOC
The protocol_dump822 function prints headers from a specified pblock 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.
char *protocol_dump822(pblock *pb, char *t, int *pos, int tsz);
A pointer to the buffer, which will be reallocated if necessary.
The function also modifies *pos to the end of the headers in the buffer.
pblock *pb is the pblock structure.
char *t is the buffer, allocated with MALLOC, CALLOC, or STRDUP.
int *pos is the position within the buffer at which the headers are to be
dumped.
int tsz is the size of the buffer.
protocol_start_response, protocol_status
The protocol_set_finfo function retrieves the content-length and last-modified date from a specified stat structure and adds them to the response headers (rq->srvhdrs). Call protocol_set_finfo before calling protocol_start_response.
int protocol_set_finfo(Session *sn, Request *rq, struct stat
*finfo);
The constant REQ_PROCEED if the request can proceed normally or the constant
REQ_ABORTED if the function should treat the request normally, but not send
any output to the client
Session *sn is the Session.
Request *rq is the Request.
The Session and Request parameters are the same as the ones passed into your
SAF.
stat *finfo is the stat structure for the file.
The stat structure contains the information about the file from the file system.
You can get the stat structure info using request_stat_path.
protocol_start_response, protocol_status
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.
int protocol_start_response(Session *sn, Request *rq);
The constant REQ_PROCEED if the operation succeeded, in which case you
should send the data you were preparing to send.
The constant REQ_NOACTION if the operation succeeded, but the request
method was HEAD in which case no data should be sent to the client.
The constant REQ_ABORTED if the operation did not succeed.
Session *sn is the Session.
Request *rq is the Request.
The Session and Request parameters are the same as the ones passed into
your SAF.
/* A noaction response from this function means the request was
HEAD */
if (protocol_start_response(sn, rq) == REQ_NOACTION) {
filebuf_close(groupbuf); /* close our file*/
return REQ_PROCEED;
}
protocol_status
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." The reason string is sent to the client in the HTTP response line. Use this function to set the status of the response before calling the function protocol_start_response.
The following is a list of valid status code constants:
PROTOCOL_CONTINUE
PROTOCOL_SWITCHING
PROTOCOL_OK
PROTOCOL_CREATED
PROTOCOL_NO_RESPONSE
PROTOCOL_PARTIAL_CONTENT
PROTOCOL_REDIRECT
PROTOCOL_NOT_MODIFIED
PROTOCOL_BAD_REQUEST
PROTOCOL_UNAUTHORIZED
PROTOCOL_FORBIDDEN
PROTOCOL_NOT_FOUND
PROTOCOL_METHOD_NOT_ALLOWED
PROTOCOL_PROXY_UNAUTHORIZED
PROTOCOL_CONFLICT
PROTOCOL_LENGTH_REQUIRED
PROTOCOL_PRECONDITION_FAIL
PROTOCOL_ENTITY_TOO_LARGE
PROTOCOL_URI_TOO_LARGE
PROTOCOL_SERVER_ERROR
PROTOCOL_NOT_IMPLEMENTED
PROTOCOL_VERSION_NOT_SUPPORTED
void protocol_status(Session *sn, Request *rq, int n, char *r);
void, but it sets values in the Session/Request designated by sn/rq for the
status code and the reason string
Session *sn is the Session.
Request *rq is the Request.
The Session and Request parameters are the same as the ones passed into
your SAF.
int n is one of the status code constants above.
char *r is the reason string.
/* if we find extra path-info, the URL was bad so tell the */
/* browser it was not found */
if (t = pblock_findval("path-info", rq->vars)) {
protocol_status(sn, rq, PROTOCOL_NOT_FOUND, NULL);
log_error(LOG_WARN, "function-name", sn, rq, "%s not found",
path);
return REQ_ABORTED;
}
protocol_start_response
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). See protocol_uri2url_dynamic.
If you want to omit either the URI prefix or suffix, use "" instead of NULL as the value for either parameter.
char *protocol_uri2url(char *prefix, char *suffix);
A new string containing the URL
char *prefix is the prefix.
char *suffix is the suffix.
protocol_start_response, protocol_status, pblock_nvinsert,
protocol_uri2url_dynamic
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.
The protocol_uri2url_dynamic function is similar to 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.
char *protocol_uri2url(char *prefix, char *suffix, Session *sn,
Request *rq);
A new string containing the URL
char *prefix is the prefix.
char *suffix is the suffix.
Session *sn is the Session.
Request *rq is the Request.
The Session and Request parameters are the same as the ones passed into
your SAF.
protocol_start_response, protocol_status, protocol_uri2url
The REALLOC macro is a platform-independent substitute for the C library routine realloc. It changes the size of a specified memory block that was originally created by MALLOC, CALLOC, or STRDUP. The contents of the object remains unchanged up to the lesser of the old and new sizes. If the new size is larger, the new space is uninitialized.
Calling REALLOC for a block that was allocated with PERM_MALLOC,
PERM_CALLOC, or PERM_STRDUP will not work.
void *REALLOC(void *ptr, int size);
A pointer to the new space if the request could be satisfied.
void *ptr is a (void *) pointer to a block of memory. If the pointer is not one
created by MALLOC, CALLOC, or STRDUP, the behavior is undefined.
int size is the number of bytes to allocate.
char *name;
name = (char *) MALLOC(256);
if (NotBigEnough())
name = (char *) REALLOC(512);
MALLOC, FREE, STRDUP, CALLOC, PERM_MALLOC, PERM_FREE,
PERM_REALLOC, PERM_CALLOC, PERM_STRDUP
The request_header function finds an entry in the pblock containing the client's HTTP request headers (rq->headers). You must use this function rather than pblock_findval when accessing the client headers since the server may begin processing the request before the headers have been completely
int request_header(char *name, char **value, Session *sn,
Request *rq);
A result code, REQ_PROCEED if the header was found, REQ_ABORTED if the
header was not found, REQ_EXIT if there was an error reading from the client.
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.
Request *rq is the Request.
The Session and Request parameters are the same as the ones passed into
your SAF.
request_create, request_free
The request_stat_path function returns the file information structure for a specified path or, if none is specified, the path entry in the vars pblock in the specified Request structure. If the resulting file name 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, its owner, when it was created, and when it was last modified.
You should 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 previous calls for the same path and returns its cached information.
struct stat *request_stat_path(char *path, Request *rq);
Returns a pointer to the file information structure for the file named by the
path parameter. Do not free this structure. 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 rq->staterr.
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.
fi = request_stat_path(path, rq);
request_create, request_free, request_header
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 would be sent back if a given URI is accessed.
char *request_translate_uri(char *uri, Session *sn);
A path string, if it performed the mapping or NULL if it could not perform the
mapping
char *uri is the name of the URI.
Session *sn is the Session parameter that is passed into your SAF.
request_create, request_free, request_header
The session_maxdns function resolves the IP address of the client associated with a specified session into its DNS name. It returns a newly allocated string. You can use session_maxdns to change the numeric IP address into something more readable.
char *session_maxdns(Session *sn);
A string containing the host name or NULL if the DNS name cannot be found
for the IP address
Session *sn is the Session.
The Session is the same as the one passed to your SAF.
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. The comparison (in contrast to that of the shexp_cmp function) 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.
int shexp_casecmp(char *str, char *exp);
0 if a match was found.
1 if no match was found.
-1 if the comparison resulted in an invalid expression.
char *str is the string to be compared.
char *exp is the shell expression (wildcard pattern) to compare against.
shexp_cmp, shexp_match, shexp_valid
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. The comparison (in contrast to that of the shexp_casecmp function) 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.
int shexp_cmp(char *str, char *exp);
0 if a match was found.
1 if no match was found.
-1 if the comparison resulted in an invalid expression.
char *str is the string to be compared.
char *exp is the shell expression (wildcard pattern) to compare against.
/* Use wildcard match to see if this path is one we want */
char *path;
char *match = "/usr/netscape/*";
if (shexp_cmp(path, match) != 0)
return REQ_NOACTION; /* no match */
shexp_casecmp, shexp_match, shexp_valid
The shexp_match function compares a specified pre-validated shell expression against a specified string. It returns one of three possible values representing match, no match, and invalid comparison. The comparison (in contrast to that of the shexp_casecmp function) 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.
int shexp_match(char *str, char *exp);
0 if a match was found.
1 if no match was found.
-1 if the comparison resulted in an invalid expression.
char *str is the string to be compared.
char *exp is the pre-validated shell expression (wildcard pattern) to compare
against.
shexp_casecmp, shexp_cmp, shexp_valid
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.
int shexp_valid(char *exp);
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.
char *exp is the shell expression (wildcard pattern) to be validated.
shexp_casecmp, shexp_match, shexp_cmp
The STRDUP macro is a platform-independent substitute for the C library routine strdup. It creates a new copy of a string in the request's memory pool.
The STRDUP routine is functionally equivalent to:
newstr = (char *) MALLOC(strlen(str) + 1);
strcpy(newstr, str);
A string created with STRDUP should be disposed with FREE.
char *STRDUP(char *ptr);
A pointer to the new string.
char *ptr is a pointer to a string.
char *name1 = "MyName";
char *name2 = STRDUP(name1);
MALLOC, FREE, CALLOC, REALLOC, PERM_MALLOC, PERM_FREE,
PERM_CALOC, PERM_REALLOC, PERM_STRDUP
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.
char *system_errmsg(int param1);
A string containing the text of the latest error message that resulted from a
system call. Do not FREE this string.
int param1 is reserved, and should always have the value 0.
system_fopenRO, system_fopenRW, system_fopenWA, system_lseek,
system_fread, system_fwrite, system_fwrite_atomic,
system_flock, system_ulock, system_fclose
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.
int system_fclose(SYS_FILE fd);
0 if the close succeeded or the constant IO_ERROR if the close failed.
SYS_FILE fd is the platform-independent file descriptor.
SYS_FILE logfd;
system_fclose(logfd);
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA,
system_lseek, system_fread, system_fwrite,
system_fwrite_atomic, system_flock, system_ulock
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.
int system_flock(SYS_FILE fd);
The constant IO_OK if the lock succeeded or the constant IO_ERROR if the lock
failed
SYS_FILE fd is the platform-independent file descriptor.
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA,
system_lseek, system_fread, system_fwrite,
system_fwrite_atomic, system_ulock, system_fclose
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.
SYS_FILE system_fopenRO(char *path);
The system-independent file descriptor (SYS_FILE) if the open succeeded or 0
if the open failed
char *path is the file name.
system_errmsg, system_fopenRW, system_fopenWA, system_lseek,
system_fread, system_fwrite, system_fwrite_atomic,
system_flock, system_ulock, system_fclose
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.
SYS_FILE system_fopenRW(char *path);
The system-independent file descriptor (SYS_FILE) if the open succeeded or 0
if the open failed.
char *path is the file name.
SYS_FILE fd;
fd = system_fopenRO(pathname);
if (fd == SYS_ERROR_FD)
break;
system_errmsg, system_fopenRO, system_fopenWA, system_lseek,
system_fread, system_fwrite, system_fwrite_atomic,
system_flock, system_ulock, system_fclose
The system_fopenWA function opens the file identified by path in write-append mode and returns a valid file descriptor. Use this function to open those files that your program will append data to.
SYS_FILE system_fopenWA(char *path);
The system-independent file descriptor (SYS_FILE) if the open succeeded or 0
if the open failed.
char *path is the file name.
system_errmsg, system_fopenRO, system_fopenRW, system_lseek,
system_fread, system_fwrite, system_fwrite_atomic,
system_flock, system_ulock, system_fclose
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.
int system_fread(SYS_FILE fd, char *buf, int sz);
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
were obtained.
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.
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA,
system_lseek, system_fwrite, system_fwrite_atomic,
system_flock, system_ulock, system_fclose
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.
int system_fwrite(SYS_FILE fd, char *buf, int sz);
The constant IO_OK if the write succeeded or the constant IO_ERROR if the
write failed.
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.
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA,
system_lseek, system_fread, system_fwrite_atomic, system_flock,
system_ulock, system_fclose
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, except system_fopenRO.
int system_fwrite_atomic(SYS_FILE fd, char *buf, int sz);
The constant IO_OK if the write/lock succeeded or the constant IO_ERROR if the
write/lock failed.
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.
SYS_FILE logfd;
char *logmsg = "An error occurred.";
system_fwrite_atomic(logfd, logmsg, strlen(logmsg));
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA,
system_lseek, system_fread, system_fwrite, system_flock,
system_ulock, system_fclose
The system_gmtime function is a thread-safe version of the standard gmtime function. It returns the current time adjusted to Greenwich Mean Time.
struct tm *system_gmtime(const time_t *tp, const struct tm
*res);
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.
time_t *tp is an arithmetic time.
tm *res is a pointer to a calendar time (tm) structure.
time_t tp;
struct tm res, *resp;
tp = time(NULL);
resp = system_gmtime(&tp, &res);
system_localtime, util_strftime
The system_localtime function is a thread-safe version of the standard localtime function. It returns the current time in the local time zone.
struct tm *system_localtime(const time_t *tp, const struct tm
*res);
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.
time_t *tp is an arithmetic time.
tm *res is a pointer to a calendar time (tm) structure.
system_gmtime, util_strftime
The10system_lseek function sets the file position of a file. This affects where data from system_fread or system_fwrite is read or written.
int system_lseek(SYS_FILE fd, int offset, int whence);
the offset, in bytes, of the new position from the beginning of the file if the
operation succeeded or -1 if the operation failed.
SYS_FILE fd is the platform-independent file descriptor.
int offset is a number of bytes relative to whence. It may be negative.
int whence is a one of the following constants:
SEEK_SET, from the beginning of the file.
SEEK_CUR, from the current file position.
SEEK_END, from the end of the file.
system_errmsg, system_fopenRO, system_fopenRW, system_fopenWA,
system_fread, system_fwrite, system_fwrite_atomic,
system_flock, system_ulock, system_fclose
The system_rename function renames a file. It may not work on directories if the old and new directories are on different file systems.
int system_rename(char *old, char *new);
0 if the operation succeeded or -1 if the operation failed.
char *old is the old name of the file.
char *new is the new name for the file:
The system_ulock function unlocks the specified file that has been locked by the function system_lock