Skip to ContentSun and Oracle Channel Sun How to Buy Log In

Sun Java System Web Server 7.0 Update 1 NSAPI Developer's Guide

Contained Within

Sun Java System Web Server 7.0 Update 1

Find More Documentation

Featured Support Resources

Download this book in PDF (1494 KB)

Chapter 6 NSAPI Function and Macro Reference

This chapter lists all the public C functions and macros of the Netscape Server Applications Programming Interface (NSAPI). Use these functions when writing your own Server Application Functions (SAFs) and filters.

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 Chapter 7, Data Structure Reference.

NSAPI Functions and Macros

For an alphabetical list of function names, see Appendix B, Alphabetical List of NSAPI Functions and Macros.

C

`CALLOC()` Macro

The CALLOC macro is a platform-independent substitute for the C library routine calloc. It allocates size bytes from the request’s memory pool and initializes the memory to zeros. The memory can be explicitly freed by a call to FREE. If the memory is not explicitly freed, it is automatically freed after processing of the current request 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. However, because memory allocated by CALLOCis automatically freed, the memory should not be shared with threads.

Syntax

void *CALLOC(int size)

Return Values

A void pointer to a block of memory.

Parameters

int size is the number of bytes to allocate.

Example

char *name;
name = (char *) CALLOC(100);

`cinfo_find()` Function

The cinfo_find() function uses the MIME types information to find the type, encoding, or language based on the extensions 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 the client will be receiving from the server.

The URI name used is everything after the last slash (/) or the whole string if no slash is found. File name extensions are not casesensitive. The name can contain multiple extensions separated by a period (.) to indicate type, encoding, or language. For example, the URI a/b/filename.jp.txt.zip represents a Japanese language, text/plain type, zip-encoded file.

Syntax

cinfo *cinfo_find(char *uri);

Returns

A pointer to a newly allocated cinfo structure if the find succeeds, or NULL if the find fails.

The cinfo structure that is allocated and returned contains pointers to the content-type, content-encoding, and content-language, if found. Each structure points to static data in the types database, or NULL if not found. Do not free these pointers. You should free the cinfo structure after using it.

Parameters

char *uri is a Universal Resource Identifier (URI) or local file name. Multiple file name extensions should be separated by periods (.).

`condvar_init()` Function

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.

Syntax

CONDVAR condvar_init(CRITICAL id);

Return Values

A newly allocated condition variable (CONDVAR).

Parameters

CRITICAL id is a critical-section variable.

`condvar_notify()` Function

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

void condvar_notify(CONDVAR cv);

Return Values

void

Parameters

CONDVAR cv is a condition variable.

`condvar_terminate()` Function

The condvar_terminate function is a 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

void condvar_terminate(CONDVAR cv);

Return Values

void

Parameters

CONDVAR cv is a condition variable.

`condvar_wait()` Function

The condvar_wait function is a 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

void condvar_wait(CONDVAR cv);

Return Values

void

Parameters

CONDVAR cv is a condition variable.

`crit_enter()` Function

The crit_enter function is a 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

void crit_enter(CRITICAL crvar);

Return Values

void

Parameters

CRITICAL crvar is a critical-section variable.

`crit_exit()` Function

The crit_exit function is a 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 is removed and the waiting thread is given ownership of the section.

Syntax

void crit_exit(CRITICAL crvar);

Return Values

void

Parameters

CRITICAL crvar is a critical-section variable.

`crit_init()` Function

The crit_init function is a 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. Use this variable to prevent interference between two threads of execution. At the time this variable is created, no thread owns the critical section.

Caution –

Threads must not own or be waiting for the critical section when crit_terminate is called.

Syntax

CRITICAL crit_init(void);

Return Values

A newly allocated critical-section variable (CRITICAL).

Parameters

none

`crit_terminate()` Function

The crit_terminate function is a 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.

Syntax

void crit_terminate(CRITICAL crvar);

Return Values

void

Parameters

CRITICAL crvar is a critical-section variable.

D

`daemon_atrestart()` Function

The daemon_atrestart function enables to you register a callback function named fn to be used when the server terminates. 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.

The magnus.conf directives TerminateTimeout and ChildRestartCallback also affect the callback of NSAPI functions.

Syntax

void daemon_atrestart(void (*fn)(void *), void *data);

Return Values

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

/* Register the log_close 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);}

F

`filebuf_buf2sd()` Function

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.

Syntax

int filebuf_buf2sd(filebuf *buf, SYS_NETFD sd);

Return Values

The number of bytes sent to the socket if successful, or the constant IO_ERROR if the file buffer cannot be sent.

Parameters

filebuf *buf is the file buffer that must already have been opened.

SYS_NETFD sd is the platform-independent socket descriptor. Normally this parameter is obtained from the csd, client socket descriptor field of the sn or the session structure.

Example

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

`filebuf_close()` Function

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.

Syntax

void filebuf_close(filebuf *buf);

Return Values

void

Parameters

filebuf *buf is the file buffer previously opened with filebuf_open.

Example

filebuf_close(buf);

`filebuf_getc()` Function

The filebuf_getc function retrieves a character from the current file position and returns the character as an integer. The function then increments the current file position.

Use filebuf_getc to sequentially read characters from a buffered file.

Syntax

filebuf_getc(filebuf b);

Return Values

An integer containing the character retrieved, or the constant IO_EOF or IO_ERROR upon an end of file or an error.

Parameters

filebuf b is the name of the file buffer.

`filebuf_open()` Function

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.

Syntax

filebuf *filebuf_open(SYS_FILE fd, int sz);

Return Values

A pointer to a new buffer structure to hold the data if successful, or NULL if no buffer can be opened.

Parameters

SYS_FILE fd is the platform-independent file descriptor of the file that has already been opened.

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

Example

filebuf *buf = filebuf_open(fd, FILE_BUFFERSIZE);
if (!buf) 
{    
   system_fclose(fd);
}

`filebuf_open_nostat()` Function

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 as filebuf_open, but is more efficient, because it does not need to call the request_stat_path function. This function requires that the stat information be passed in.

Syntax

filebuf* filebuf_open_nostat(SYS_FILE fd, int sz, struct stat *finfo);

Return Values

A pointer to a new buffer structure to hold the data if successful, or NULL if no buffer can be opened.

Parameters

SYS_FILE fd is the platform-independent file descriptor of the file that 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.

Example

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

`filter_create()` Function

The filter_create function defines a new filter.

The name parameter specifies a unique name for the filter. If a filter with the specified name already exists, it will be replaced.

Names beginning with magnus- or server- are reserved by the server.

The order parameter indicates the position of the filter in the filter stack by specifying what class of functionality the filter implements.

The following table describes parameters allowed constants and their associated meanings for the filter_create function. The left column lists the name of the constant, the middle column describes the functionality the filter implements, and the right column lists the position the filter occupies in the filter stack.

Table 6–1 filter-create() Constants


Constant	Functionality Filter Implements	Position in Filter Stack
`FILTER_CONTENT_TRANSLATION`	Translates content from one form to another, for example, XSLT	Top
`FILTER_CONTENT_CODING`	Encodes content, for example, HTTP `gzip` compression	Middle
`FILTER_TRANSFER_CODING`	Encodes entity bodies for transmission, for example, HTTP chunking	Bottom

The methods parameter specifies a pointer to a FilterMethods structure. Before calling filter_create, you must initialize the FilterMethods structure using the FILTER_METHODS_INITIALIZER macro, and then assign function pointers to the individual FilterMethods members (for example, insert, read, write, and so on) that correspond to the filter methods the filter supports.

filter_create returns const Filter *, a pointer to an opaque representation of the filter. This value can be passed to filter_insert to insert the filter in a particular filter stack.

Syntax

const Filter *filter_create(const char *name, int order, 
                            const FilterMethods *methods);

Return Values

The const Filter * that identifies the filter, or NULL if an error occurs.

Parameters

const char *name is the name of the filter.

int order is one of the order constants listed in Table Table 6–1.

const FilterMethods *methods contains pointers to the filter methods the filter supports.

Example

FilterMethods methods = FILTER_METHODS_INITIALIZER;
const Filter *filter;
/* This filter will only support the "read" filter method */
methods.read = my_input_filter_read;
/* Create the filter */
filter = filter_create("my-input-filter", FILTER_CONTENT_TRANSLATION,
                        &methods);

`filter_find()` Function

The filter_find function finds the filter with the specified name.

Syntax

const Filter *filter_find(const char *name);

Return Values

The const Filter * that identifies the filter, or NULL if the specified filter does not exist.

Parameters

const char *name is the name of the filter of interest.

`filter_insert()` Function

The filter_insert function inserts a filter into a filter stack, creating a new filter layer and installing the filter at that layer. The filter layer's position in the stack is determined by the order specified when filter_create was called, and any explicit ordering configured by init-filter-order. If a filter layer with the same order value already exists in the stack, the new layer is inserted above that layer.

Parameters are passed to the filter using the pb and data parameters. The semantics of the data parameter are defined by individual filters. However, all filters must be able to handle a data parameter of NULL.

Note –

When possible, plug-in developers should avoid calling filter_insert directly, and instead use the insert-filter SAF.

Syntax

int filter_insert(SYS_NETFD sd, pblock *pb, Session *sn, Request *rq, 
                  void *data, const Filter *filter);

Return Values

REQ_PROCEED if the specified filter was inserted successfully, or REQ_NOACTION if the specified filter was not inserted because it was not required. Any other return value indicates an error.

Parameters

SYS_NETFD sd is NULL, and is reserved for future use.

pblock *pb is a set of parameters to pass to the specified filter's init() method.

Session *sn is the session.

Request *rq is the request.

void *data is filter-defined private data.

const Filter *filter is the filter to insert.

`filter_layer()` Function

The filter_layer function returns the layer in a filter stack that corresponds to the specified filter.

Syntax

FilterLayer *filter_layer(SYS_NETFD sd, const Filter *filter);

Return Values

The topmost FilterLayer * associated with the specified filter, or NULL if the specified filter is not part of the specified filter stack.

Parameters

SYS_NETFD sd is the filter stack to inspect.

const Filter *filter is the filter of interest.

`filter_name()` Function

The filter_name function returns the name of the specified filter. The caller should not free the returned string.

Syntax

const char *filter_name(const Filter *filter);

Return Values

The name of the specified filter, or NULL if an error occurred.

Parameters

const Filter *filter is the filter of interest.

`filter_remove()` Function

The filter_remove function removes the specified filter from the specified filter stack, destroying a filter layer. If the specified filter was inserted into the filter stack multiple times, only the top filter layer of the filter is destroyed.

Note –

When possible, plug-in developers should avoid calling filter_remove directly, and instead use the remove-filter() SAF. this recommendation is applicable in Input-, Output-, Service-, and Error-class directives.

Syntax

int filter_remove(SYS_NETFD sd, const Filter *filter);

Return Values

REQ_PROCEED if the specified filter was removed successfully, or REQ_NOACTION if the specified filter was not part of the filter stack. Any other return value indicates an error.

Parameters

SYS_NETFD sd is the filter stack, sn->csd.

const Filter *filter is the filter to remove.

`flush()` Function

The flush filter method is called when buffered data should be sent. Filters that buffer outgoing data should implement the flush filter method.

Upon receiving control, a flush implementation must write any buffered data to the filter layer immediately below it. Before returning success, a flush implementation must successfully call the net_flush function:

net_flush(layer->lower).

Syntax

int flush(FilterLayer *layer);

Return Values

0 on success or -1 if an error occurs.

Parameters

FilterLayer *layer is the filter layer the filter is installed in.

Example

int myfilter_flush(FilterLayer *layer)
{
    MyFilterContext context = (MyFilterContext *)layer->context->data;
    if (context->buf.count) {
       int rv;
       rv = net_write(layer->lower, context->buf.data, context->buf.count);
       if (rv != context->buf.count)
           return -1; /* failed to flush data */
       context->buf.count = 0;
    }
    return net_flush(layer->lower);
}

`FREE()` Macro

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.

Note –

Calling FREE for a block that was allocated with PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP will not work.

Syntax

FREE(void *ptr);

Return Values

void

Parameters

void *ptr is a (void *) pointer to a block of memory. If the pointer is not the one created by MALLOC, CALLOC, or STRDUP, the behavior is undefined.

Example

char *name;
name = (char *) MALLOC(256);
...
...
FREE(name);

`func_exec()` Function

The func_exec function executes the function named by the fn entry in a specified pblock. If the function name is not found, func_exec 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.

Syntax

int func_exec(pblock *pb, Session *sn, Request *rq);

Return Values

The value returned by the executed function, or the constant if successful. REQ_ABORTED, if no function is executed.

Parameters

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 parameters as the ones passed into the custom SAF.

`func_find()` Function

The func_find function returns a pointer to the function specified by name. If the function does not exist, func_find returns NULL.

Syntax

FuncPtr func_find(char *name);

Return Values

A pointer to the chosen function, suitable for de-referencing, or NULL if the function is not 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);

`func_insert()` Function

The func_insert function dynamically inserts a named function into the server's table of functions. This function should only be called during the Init stage.

Syntax

FuncStruct *func_insert(char *name, FuncPtr fn);

Return Values

The FuncStruct structure that identifies the newly inserted function. The caller should not modify the contents of the FuncStruct structure.

Parameters

char *name is the name of the function.

FuncPtr fn is the pointer to the function.

Example

func_insert("my-service-saf", &my_service_saf);

I

`insert()` Function

The insert filter method is called when a filter is inserted into a filter stack by the filter_insert function or insert-filter SAF.

Syntax

int insert(FilterLayer *layer, pblock *pb);

Return Values

REQ_PROCEED if the filter should be inserted into the filter stack, REQ_NOACTION if the filter should not be inserted because it is not required, or REQ_ABORTED if the filter should not be inserted because of an error.

Parameters

FilterLayer *layer is the filter layer at which the filter is being inserted.

pblock *pb is the set of parameters passed to filter_insert or specified by the fn="insert-filter" directive.

Example

int myfilter_insert(FilterLayer *layer, pblock *pb)
{    
	    if (pblock_findval("dont-insert-filter", pb))
        return REQ_NOACTION;
        return REQ_PROCEED;
}
...

FilterMethods myfilter_methods = FILTER_METHODS_INITIALIZER;
const Filter *myfilter;

myfilter_methods.insert = &myfilter_insert;    
myfilter = filter_create("myfilter", &myfilter_methods);
...

L

`log_error()` Function

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

Syntax

int log_error(int degree, char *func, Session *sn, Request *rq, char *fmt, ...);

Return Values

0 if the log entry is created, or -1 if the log entry is not created.

Parameters

int degree specifies the severity of the error. The parameter value must be one of the following constants:

LOG_VERBOSE — Debug message
LOG_VERBOSE —Debug message
LOG_INFORM — Information message
LOG_WARN— Warning
LOG_FAILURE — Operation failed
LOG_MISCONFIG— Misconfiguration
LOG_SECURITY — Authentication or authorization failure
LOG_CATASTROPHE— Nonrecoverable server error

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

Session *sn is the session.

Request *rq is the request.

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

Example

log_error(LOG_WARN, "send-file", sn, rq, "error opening buffer from %s (%s)"),
           path, system_errmsg(fd));

M

`MALLOC()` Macro

The MALLOC macro is a platform-independent substitute for the C library routine malloc. It allocates size bytes from the requests's memory pool. The memory can be explicitly freed by a call to FREE. If the memory is not explicitly freed, it is automatically freed after processing of the current request has been completed. If pooled memory has been disabled in the configuration file with the built-in SAF pool-init, PERM_MALLOC and MALLOC both obtain their memory from the system heap. However, because memory allocated by MALLOC is automatically freed, it should not be shared between threads.

If pooled memory has been disabled in the configuration file with the built-in SAF pool-init,, PERM_MALLOC and MALLOC both obtain their memory from the system heap.

Syntax

void *MALLOC(int size)

Return Values

A void pointer to a block of memory.

Parameters

int size is the number of bytes to allocate.

Example

/* Allocate 256 bytes for a name */
char *name;
name = (char *) MALLOC(256);

N

`net_flush()` Function

The net_flush function flushes any buffered data. If you require that data be sent immediately, call net_flush after calling the network output functions such as net_write or net_sendfile.

Syntax

int net_flush(SYS_NETFD sd);

Return Values

0 on success, or a negative value if an error occurs.

Parameters

SYS_NETFD sd is the socket to flush.

Example

net_write(sn->csd, "Please wait... ", 15);
net_flush(sn->csd);
/* Perform some time-intensive operation */
...
net_write(sn->csd, "Thank you.\n", 11);

`net_ip2host()` Function

The net_ip2host function transforms a textual IP address into a fullyqualified domain name and returns the name.

Note –

This function works only if the DNS directive is enabled in the magnus.conf file.

Syntax

char *net_ip2host(char *ip, int verify);

Return Values

A new string containing the fullyqualified domain name if the transformation is accomplished, or NULL if the transformation is 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 fullyqualified domain name. Though this verification requires an extra query, you should use it when checking the access control.

`net_read()` Function

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

int net_read (SYS_NETFD sd, char *buf, int sz, int timeout);

Return Values

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.

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 to limit the amount of time devoted to waiting until some data arrives.

`net_sendfile()` Function

The net_sendfile function sends the contents of a specified file to a specified a socket. Either the whole file or a fraction might be sent, and the contents of the file might optionally be preceded or followed by caller-specified data.

Parameters are passed to net_sendfile in the sendfiledata structure. Before invoking net_sendfile, the caller must initialize every sendfiledata structure member.

Syntax

int net_sendfile(SYS_NETFD sd, const sendfiledata *sfd);

Return Values

A positive number indicating the number of bytes successfully written, including the headers, file contents, and trailers. A negative value indicates an error.

Parameters

SYS_NETFD sd is the socket to write to.

const sendfiledata *sfd identifies the data to send.

Example

The following Service SAF sends a file bracketed by the strings "begin" and "end."

#include <string.h>
#include "nsapi.h"

NSAPI_PUBLIC int service_net_sendfile(pblock *pb, Session *sn, Request *rq)
{
    char *path;
    SYS_FILE fd;
    struct sendfiledata sfd;
    int rv;

    path = pblock_findval("path", rq->vars);
    fd = system_fopenRO(path);
    if (!fd) {
        log_error(LOG_MISCONFIG, "service-net-sendfile", sn, rq,
                  "Error opening %s (%s)", path, system_errmsg());
        return REQ_ABORTED;
    }

    sfd.fd = fd;                     /* file to send */
    sfd.offset = 0;                  /* start sending from the beginning */
    sfd.len = 0;                     /* send the whole file */
    sfd.header = "begin";            /* header data to send before the file */
    sfd.hlen = strlen(sfd.header);   /* length of header data */
    sfd.trailer = "end";             /* trailer data to send after the file */
    sfd.tlen = strlen(sfd.trailer);  /* length of trailer data */

    /* send the headers, file, and trailers to the client */
    rv = net_sendfile(sn->csd, &sfd);

    system_fclose(fd);

    if (rv < 0) {
        log_error(LOG_INFORM, "service-net-sendfile", sn, rq,
                 "Error sending %s (%s)", path, 
                 system_errmsg());
        return REQ_ABORTED;
    }

    return REQ_PROCEED;
}

`net_write()` Function

The net_write function writes a specified number of bytes to a specified socket from a specified buffer.

Syntax

int net_write(SYS_NETFD sd, char *buf, int sz);

Return Values

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

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

if (net_write(sn->csd, FIRSTMSG, strlen(FIRSTMSG)) == IO_ERROR)
    return REQ_EXIT;

`netbuf_buf2sd()` Function

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

int netbuf_buf2sd(netbuf *buf, SYS_NETFD sd, int len);

Return Values

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

Parameters

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

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.

Never close the netbuf parameter in a session structure.

Syntax

void netbuf_close(netbuf *buf);

Return Values

void

Parameters

netbuf *buf is the buffer to close.

`netbuf_getbytes()` Function

The netbuf_getbytes function reads bytes from a network buffer into a caller-supplied buffer. If the network buffer is empty, the function waits to receive data from the network buffer's socket until either at least one byte is available from the socket or the network buffer's timeout has elapsed.

Syntax

int netbuf_getbytes(netbuf *buf, char *buffer, int sz);

Return Values

The number of bytes placed into the buffer between 1 and sz if the operation is successful, the constant NETBUF_EOF on end of file, or the constant NETBUF_ERROR if an error occurred.

Parameters

netbuf *buf is the buffer from which to retrieve bytes.

char *buffer is the caller-supplied buffer that receives the bytes.

int sz is the maximum number of bytes to read.

Example

int cl = 0;

* Read the entire request body */
for (;;) {
     char mybuf[1024];
     int rv;

     rv = netbuf_getbytes(sn->inbuf, mybuf, sizeof(mybuf));
     if (rv == NETBUF_EOF) {
         log_error(LOG_INFORM, "mysaf", sn, rq,
                   "Received %d byte(s)",
                   cl);
         break;
     }
     if (rv == NETBUF_ERROR) {
         log_error(LOG_FAILURE, "mysaf", sn, rq,
                   "Error reading request body (%s)",
                   cl, system_errmsg());
         break;     }

     cl += rv;
}

`netbuf_getc()` Function

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

Note –

Because the constant IO_EOF has a value of 0, netbuf_getc cannot be used to read data that might contain a null character. To read binary data, use netbuf_getbytes() Function or netbuf_grab() Function.

Syntax

netbuf_getc(netbuf b);

Return Values

The integer representing the character if a character is retrieved, or the constant IO_EOF or IO_ERROR for end of file or an error.

Parameters

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

`netbuf_grab()` Function

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.

Syntax

int netbuf_grab(netbuf *buf, int sz);

Return Values

The number of bytes actually read between 1 and sz if the operation is successful, or the constant IO_EOF or IO_ERROR for end of file or an error.

Parameters

netbuf *buf is the buffer to read into.

int sz is the number of bytes to read.

`netbuf_open()` Function

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

netbuf* netbuf_open(SYS_NETFD sd, int sz);

Return Values

A pointer to a new netbufnetwork buffer structure.

Parameters

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

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

`nsapi_module_init()` Function

Defines the nsapi_module_init function, which is a module initialization entry point that enables a plug-in to create filters when it is loaded. When an NSAPI module contains an nsapi_module_init function, the server will call that function immediately after loading the module. The nsapi_module_init presents the same interface as an Init SAF, and it must follow the same rules.

Use the nsapi_module_init function to register SAFs with func_insert, create filters with filter_create, register virtual server initialization/destruction callbacks with vs_register_cb, and perform other initialization tasks.

Syntax

int nsapi_module_init(pblock *pb, Session *sn, Request *rq);

Return Values

REQ_PROCEED on success, or REQ_ABORTED on error.

Parameters

pblock *pb is a set of parameters specified by the fn="load-modules" directive.

Session *sn (the session) is NULL.

Request *rq (the request) is NULL.

`NSAPI_RUNTIME_VERSION()` Macro

The NSAPI_RUNTIME_VERSION macro defines the NSAPI version available at runtime. This version is the same as the highest NSAPI version supported by the server the plug-in is running in. The NSAPI version is encoded as in USE_NSAPI_VERSION.

The value returned by the NSAPI_RUNTIME_VERSION macro is valid only in iPlanet™ Web Server 6.0, Netscape Enterprise Server 6.0, Sun ONE Web Server 6.1, and Sun Java System Web Server 7.0 Update 1. The server must support NSAPI 3.1 for this macro to return a valid value. Additionally, to use NSAPI_RUNTIME_VERSION, you must compile against an nsapi.h header file that supports NSAPI 3.2 or higher.

Do not attempt to set the value of the NSAPI_RUNTIME_VERSION macro directly. Instead, use the USE_NSAPI_VERSION macro.

Syntax

int NSAPI_RUNTIME_VERSION

Example

NSAPI_PUBLIC int log_nsapi_runtime_version(pblock *pb, Session *sn, Request *rq) 
{
    log_error(LOG_INFORM, "log-nsapi-runtime-version", sn, rq,
                "Server supports NSAPI version %d.%d\n",
                NSAPI_RUNTIME_VERSION / 100,
                NSAPI_RUNTIME_VERSION % 100);
     return REQ_PROCEED;
}

`NSAPI_VERSION()` Macro

The NSAPI_VERSION macro defines the NSAPI version used at compile time. This value is determined by the value of the USE_NSAPI_VERSION macro or by the highest NSAPI version supported by the nsapi.h header the plug-in was compiled against. The NSAPI version is encoded as in USE_NSAPI_VERSION.

Do not attempt to set the value of the NSAPI_VERSION macro directly. Instead, use the USE_NSAPI_VERSION macro.

Syntax

int NSAPI_VERSION

Example

NSAPI_PUBLIC int log_nsapi_compile_time_version(pblock *pb, Session *sn, Request *rq) 
{
    log_error(LOG_INFORM, "log-nsapi-compile-time-version", sn, rq,
            "Plugin compiled against NSAPI version %d.%d\n",
            NSAPI_VERSION / 100,
            NSAPI_VERSION % 100);
    return REQ_PROCEED;
}

P

`param_create()` Function

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.

Syntax

pb_param *param_create(char *name, char *value);

Return Values

A pointer to a new pb_param structure.

Parameters

char *name is the string containing the name.

char *value is the string containing the value.

Example

pb_param *newpp = param_create("content-type","text/plain");
pblock_pinsert(newpp, rq->srvhdrs);

`param_free()` Function

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.

Syntax

int param_free(pb_param *pp);

Return Values

1 if the parameter is freed or 0 if the parameter is NULL.

Parameters

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

Example

if (param_free(pblock_remove("content-type", rq-srvhdrs)))    
return; /* we removed it */

`pblock_copy()` Function

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.

Syntax

void pblock_copy(pblock *src, pblock *dst);

Return Values

void

Parameters

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

The pblock_create function creates a new pblock. The pblock maintains an internal hash table for fast name-value pair lookups. Because the pblock is allocated from the request's memory pool, it should not be shared between threads.

Syntax

pblock *pblock_create(int n);

Return Values

A pointer to a newly allocated pblock.

Parameters

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

`pblock_dup()` Function

The pblock_dup function duplicates a pblock. This function is equivalent to a sequence of pblock_create and pblock_copy functions.

Syntax

pblock *pblock_dup(pblock *src);

Return Values

A pointer to a newly allocated pblock.

Parameters

pblock *src is the source pblock.

`pblock_find()` Function

The pblock_find macro finds a specified name-value pair entry in a pblock, and returns the pb_param structure. If you only want to find the value associated with the name, use the pblock_findval function.

Note –

Parameter names are case sensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.

Syntax

pb_param *pblock_find(char *name, pblock *pb);

Return Values

A pointer to the pb_param structure if found, or NULL if the name is not found.

Parameters

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

pblock *pb is the pblock to be searched.

`pblock_findval()` Function

The pblock_findval function finds the value associated with a specified name in a pblock. If you want to find 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 the pointer, do a STRDUP and modify the copy.

Note –

Parameter names are case-sensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.

Syntax

char *pblock_findval(char *name, pblock *pb);

Return Values

A string containing the value associated with the name if found, or NULL if no match is found.

Parameters

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

pblock *pb is the pblock to be searched.

`pblock_free()` Function

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.

Syntax

void pblock_free(pblock *pb);

Return Values

void

Parameters

pblock *pb is the pblock to be freed.

`pblock_nninsert()` Function

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.

Note –

Parameter names are case sensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.

Syntax

pb_param *pblock_nninsert(char *name, int value, pblock *pb);

Return Values

A pointer to the new pb_param structure.

Parameters

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 you want to assign a non-numerical value, then use the function pblock_nvinsert to create the parameter.

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

`pblock_nvinsert()` Function

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.

Note –

Parameter names are casesensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.

Syntax

pb_param *pblock_nvinsert(char *name, char *value, pblock *pb);

Return Values

A pointer to the newly allocated pb_param structure.

Parameters

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.

Example

pblock_nvinsert("content-type", "text/html", rq->srvhdrs);

`pblock_pb2env()` Function

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.

Syntax

char **pblock_pb2env(pblock *pb, char **env);

Return Values

A pointer to the environment.

Parameters

pblock *pb is the pblock to be copied.

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

`pblock_pblock2str()` Function

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.

Syntax

char *pblock_pblock2str(pblock *pb, char *str);

Return Values

The new version of the str parameter. If str is NULL, this string is a new string; otherwise, this string is a reallocated string. In either case, this string is allocated from the request’s memory pool.

Parameters

pblock *pb is the pblock to be copied.

char *str is the string into which the pblock is to be copied. This string 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_pinsert()` Function

The function pblock_pinsert inserts a pb_param structure into a pblock.

Note –

Parameter names are casesensitive. By convention, lowercase names are used for parameters that correspond to HTTP header fields.

Syntax

void pblock_pinsert(pb_param *pp, pblock *pb);

Return Values

void

Parameters

pb_param *pp is the pb_param structure to insert.

pblock *pb is the pblock.

`pblock_remove()` Function

The pblock_remove macro removes a specified name-value entry from a specified pblock. If you use this function, you must call param_free to deallocate the memory used by the pb_param structure.

Syntax

pb_param *pblock_remove(char *name, pblock *pb);

Return Values

A pointer to the named pb_param structure if it is found, or NULL if the named pb_param is not found.

Parameters

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_str2pblock()` Function

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

Syntax

int pblock_str2pblock(char *str, pblock *pb);

Return Values

The number of parameter pairs added to the pblock, if any, or -1 if an error occurs.

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=), the function 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.

`PERM_CALLOC()` Macro

The PERM_CALLOC macro is a platform-independent substitute for the C library routine calloc. This macro allocates size bytes of memory and initializes the memory to zeros. The memory persists after processing the current request has been completed. The memory should be explicitly freed by a call to PERM_FREE.

Syntax

void *PERM_CALLOC(int size)

Return Values

A void pointer to a block of memory.

Parameters

int size is the number of bytes to allocate.

Example

char **name;
name = (char **) PERM_CALLOC(100 * sizeof(char *));

`PERM_FREE()` Macro

The PERM_FREE macro is a platform-independent substitute for the C library routine free. This macro deallocates the persistent space previously allocated by PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP.

Note –

Calling PERM_FREE for a block that was allocated with MALLOC, CALLOC, or STRTUP will not work.

Syntax

PERM_FREE(void *ptr);

Return Values

void

Parameters

void *ptr is a (void *) pointer to a block of memory. If the pointer is not the one created by PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP, the behavior is undefined.

Example

char *name;
name = (char *) PERM_MALLOC(256);
...
PERM_FREE(name);

`PERM_MALLOC()` Macro

The PERM_MALLOC macro is a platform-independent substitute for the C library routine malloc. This macro provides allocation of memory that persists after the request that is being processed has been completed.

Syntax

void *PERM_MALLOC(int size)

Return Values

A void pointer to a block of memory.

Parameters

int size is the number of bytes to allocate.

Example

/* Allocate 256 bytes for a name */
char *name;
name = (char *) PERM_MALLOC(256);

`PERM_REALLOC()` Macro

The PERM_REALLOC macro is a platform-independent substitute for the C library routine realloc. This macro changes the size of a specified memory block that was originally created by PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP. The content 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.

Caution –

Calling PERM_REALLOC for a block that was allocated with MALLOC, CALLOC, or STRDUP does not work.

Syntax

void *PERM_REALLOC(vod *ptr, int size)

Return Values

A void pointer to a block of memory.

Parameters

void *ptr is 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.

Example

char *name;
name = (char *) PERM_MALLOC(256);
if (NotBigEnough())    
   name = (char *) PERM_REALLOC(name, 512);

`PERM_STRDUP()` Macro

The PERM_STRDUP macro is a platform-independent substitute for the C library routine strdup. This macro 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 built-in pool-init SAF PERM_STRDUP and STRDUP both obtain their memory from the system heap.

The PERM_STRDUP routine is functionally equivalent to the following code:

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

A string created with PERM_STRDUP should be disposed with PERM_FREE.

Syntax

char *PERM_STRDUP(char *ptr);

Return Values

A pointer to the new string.

Parameters

char *ptr is a pointer to a string.

`prepare_nsapi_thread()` Function

The prepare_nsapi_thread function enables threads that are not created by the server to act like server-created threads. This function must be called before any NSAPI functions are called from a thread that is not server-created.

Syntax

void prepare_nsapi_thread(Request *rq, Session *sn);

Return Values

void

Parameters

Request *rq is the request.

Session *sn is the session.

The Request and Session parameters are the same parameter as the ones passed into your SAF.

`protocol_dump822()` Function

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.

Syntax

char *protocol_dump822(pblock *pb, char *t, int *pos, int tsz);

Return Values

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.

Parameters

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 inserted.

int tsz is the size of the buffer.

`protocol_set_finfo()` Function

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.

Syntax

int protocol_set_finfo(Session *sn, Request *rq, struct stat *finfo);

Return Values

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.

Parameters

Session *sn is the session.

Request *rq is the request.

The Session and Request parameters are the same parameters 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()` Function

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 or higher, the function sends a status line followed by the response headers. Because of buffering, the status line and response headers might not be sent immediately. To flush the status line and response headers, use the net_flush function. Use this function to set up HTTP and prepare the client and server to receive the body or data of the response.

Note –

If you do not want the server to send the status line and response headers, set rq->senthdrs = 1 before calling protocol_start_response or sending any data to the client.

Syntax

int protocol_start_response(Session *sn, Request *rq);

Return Values

The constant REQ_PROCEED if the operation succeeds, in which case you should send the data you were preparing to send.

The constant REQ_NOACTION if the operation succeeds but the request method is HEAD, in which case no data should be sent to the client.

The constant REQ_ABORTED if the operation fails.

Parameters

Session *sn is the session.

Request *rq is the request.

The Session and Request parameters are the same parameters as the ones passed into your SAF.

Example

/* REQ_NOACTION means the request was HEAD */
if (protocol_start_response(sn, rq) == REQ_NOACTION) 
{  
  filebuf_close(groupbuf); /* close our file*/    
  return REQ_PROCEED;
}

`protocol_status()` Function

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 the function 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 or returning REQ_ABORTED.

For the complete list of valid status code constants, refer to the nsapi.h file.

Syntax

void protocol_status(Session *sn, Request *rq, int n, char *r);

Return Values

void

Parameters

Session *sn is the session.

Request *rq is therequest.

The Session and Request parameters are the same parameters as the ones passed into your SAF.

int n is one of the HTTP status code constants.

char *r is the reason string.

Example

/* 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_uri2url()` Function

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). Also 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.

Syntax

char *protocol_uri2url(char *prefix, char *suffix);

Return Values

A new string containing the URL.

Parameters

char *prefix is the prefix.

char *suffix is the suffix.

`protocol_uri2url_dynamic()` Function

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 function ensures that the URL it constructs refers to the host that the client specified.

Syntax

char *protocol_uri2url(char *prefix, char *suffix, Session *sn, Request *rq);

Return Values

A new string containing the URL.

Parameters

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 parameter as the ones passed into your SAF.

R

`read()` Function

The read filter method is called when input data is required. Filters that modify or consume incoming data should implement the read filter method.

Upon receiving control, a read implementation should fill buf with up to amount bytes of input data. This data can be obtained by calling the net_read() function, as shown in the example below.

Syntax

int read(FilterLayer *layer, void *buf, int amount, int timeout);

Return Values

The number of bytes placed in buf on success. 0 if no data is available, or a negative value if an error occurs.

Parameters

FilterLayer *layer is the filter layer in which the filter is installed.

void *buf is the buffer in which data should be placed.

int amount is the maximum number of bytes that should be placed in the buffer.

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

Example

int myfilter_read(FilterLayer *layer, void *buf, int amount, int timeout)
{        
    return net_read(layer->lower, buf, amount, timeout);
}

`REALLOC()` Macro

The REALLOC macro is a platform-independent substitute for the C library routine realloc. This macro 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.

Caution –

Calling REALLOC for a block that was allocated with PERM_MALLOC, PERM_CALLOC, or PERM_STRDUP will not work.

Syntax

void *REALLOC(void *ptr, int size);

Return Values

A pointer to the new space if the request is satisfied.

Parameters

void *ptr is a (void *) pointer to a block of memory. If the pointer is not the one created by MALLOC, CALLOC, or STRDUP, the behavior is undefined.

int size is the number of bytes to allocate.

Example

char *name;
name = (char *) MALLOC(256);
if (NotBigEnough())    
    name = (char *) REALLOC(name, 512);

`remove()` Function

The remove filter method is called when the filter stack is destroyed, or when a filter is removed from a filter stack by the filter_remove function or remove-filter SAF.

Note –

Waiting until the remove method is invoked might be too late to flush buffered data. For this reason, filters that buffer outgoing data should implement the flush filter method.

Syntax

void remove(FilterLayer *layer);

Return Values

void

Parameters

FilterLayer *layer is the filter layer in which the filter is installed.

`request_get_vs()` Function

The request_get_vs function finds the VirtualServer* to which a request is directed.

The returned VirtualServer* is valid only for the current request. To retrieve a virtual server ID that is valid across requests, use vs_get_id().

Syntax

const VirtualServer* request_get_vs(Request* rq);

Return Values

The VirtualServer* to which the request is directed.

Parameters

Request *rq is the request for which the VirtualServer* is returned.

`request_header()` Function

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, because the server might begin processing the request before the headers have been completely read.

Syntax

int request_header(char *name, char **value, Session *sn, Request *rq);

Return Values

A result code, REQ_PROCEED if the header was found, REQ_ABORTED if the header was not found, or REQ_EXIT if there was an error reading from the client.

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 no address 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 parameters as the ones passed into your SAF.

`request_stat_path()` Function

The request_stat_path function returns the file information structure for a specified path or, if no path 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 about the size of the file, its owner, when it was created, and when it was last modified.

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.

Syntax

struct stat *request_stat_path(char *path, Request *rq);

Return Values

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.

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

fi = request_stat_path(path, rq);

`request_translate_uri()` Function

The request_translate_uri function performs virtual-to-physical mapping on a specified URI during a specified session. Use this function to determine the file to be sent back if a given URI is accessed.

Syntax

char *request_translate_uri(char *uri, Session *sn);

Return Values

A path string if the function performed the mapping, or NULL if it could not perform the mapping.

Parameters

char *uri is the name of the URI.

Session *sn is the Session parameter that is passed into the SAF.

S

`sendfile()` Function

The sendfile filter method is called when the contents of a file are to be sent. Filters that modify or consume outgoing data can choose to implement the sendfile filter method.

If a filter implements the write filter method but not the sendfile filter method, the server will automatically translate net_sendfile() calls to net_write() calls. As a result, filters interested in the outgoing data stream do not need to implement the sendfile filter method. However, for performance reasons, filters that implement the write filter method should also implement the sendfile filter method.

Syntax

int sendfile(FilterLayer *layer, const sendfiledata *data);

Return Values

The number of bytes consumed, which might be less than the requested amount if an error occurred.

Parameters

FilterLayer *layer is the filter layer in which the filter is installed.

const sendfiledata *sfd identifies the data to send.

Example

int myfilter_sendfile(FilterLayer *layer, const sendfiledata *sfd)
{
    return net_sendfile(layer->lower, sfd);
}

`session_dns()` Function

The session_dns function resolves the IP address of the client associated with a specified session into its DNS name. The function returns a newly allocated string. You can use session_dns to change the numeric IP address into something more readable.

The session_maxdns function verifies that the client matches its claimed identity. The session_dns function does not perform this verification.

Note –

This function works only if the DNS directive is enabled in the magnus.conf file. For more information, see Appendix B, Alphabetical List of NSAPI Functions and Macros.

Syntax

char *session_dns(Session *sn);

Return Values

A string containing the host name, or NULL if the DNS name cannot be found for the IP address.

Parameters

Session *sn is the session.

The Session is the same parameter as the one passed to your SAF.

`session_maxdns()` Function

The session_maxdns function resolves the IP address of the client associated with a specified session into its DNS name. This function returns a newly allocated string. You can use session_maxdns to change the numeric IP address into something more readable.

Note –

This function works only if the DNS directive is enabled in the magnus.conf file. For more information, see Appendix B, Alphabetical List of NSAPI Functions and Macros.

Syntax

char *session_maxdns(Session *sn);

Return Values

A string containing the host name, or NULL if the DNS name cannot be found for the IP address.

Parameters

Session *sn is the Session.

The Session is the same parameter as the one passed to your SAF.

`shexp_casecmp()` Function

The shexp_casecmp function validates a specified shell expression and compares it with a specified string. This function returns one of three possible values representing match, no match, and invalid comparison. The comparison, in contrast to the comparison made by the shexp_cmp function is not casesensitive.

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

Syntax

int shexp_casecmp(char *str, char *exp);

Return Values

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 (wildcard pattern) to compare against.

`shexp_cmp()` Function

The shexp_cmp function validates a specified shell expression and compares it with a specified string. This returns one of three possible values representing match, no match, and invalid comparison. The comparison in contrast to the comparison made by the shexp_casecmp function is casesensitive.

Use this function for a shell expression like *.netscape.com and make sure that a string matches it, such as foo.netscape.com.

Syntax

int shexp_cmp(char *str, char *exp);

Return Values

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 (wildcard pattern) to compare against.

Example

/* 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_match()` Function

The shexp_match function compares a specified pre-validated shell expression against a specified string. This function returns one of three possible values representing match, no match, and invalid comparison. The comparison in contrast to the contrast made by the shexp_casecmp function is casesensitive.

The shexp_match function does not perform validation of the shell expression. To perform validation, use shexp_valid().

Use this function for a shell expression such as *.netscape.com, and make sure that a string matches it, such as foo.netscape.com.

Syntax

int shexp_match(char *str, char *exp);

Return Values

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 (wildcard pattern) to compare against.

`shexp_valid()` Function

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

int shexp_valid(char *exp);

Return Values

The constant NON_SXP if exp is a standard string.

The constant INVALID_SXP if exp is an invalid shell expression.

The constant VALID_SXP if exp is a valid shell expression.

Parameters

char *exp is the shell expression (wildcard pattern) to be validated.

`STRDUP()` Macro

The STRDUP macro is a platform-independent substitute for the C library routine strdup. This macro creates a new copy of a string in the request’s memory pool. The memory can be explicitly freed by a call to FREE. If the memory is not explicitly freed, it is automatically freed after processing the current request. If pooled memory has been disabled in the configuration file with the built-in pool-initSAF, PERM_STRDUP and STRDUP both obtain their memory from the system heap. However, because the memory allocated by STRDUP is automatically freed, do not share this memory between threads.

The STRDUP routine is functionally equivalent to:

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

Syntax

char *STRDUP(char *ptr);

Return Values

A pointer to the new string.

Parameters

char *ptr is a pointer to a string.

Example

char *name1 = "MyName";
char *name2 = STRDUP(name1);

`system_errmsg()` Function

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

char *system_errmsg(int param1);

Return Values

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

Parameters

int param1 is reserved, and should always have the value 0.

`system_fclose()` Function

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

int system_fclose(SYS_FILE fd);

Return Values

0 if the close succeeds, or the constant IO_ERROR if the close fails.

Parameters

SYS_FILE fd is the platform-independent file descriptor.

Example

SYS_FILE logfd; 
system_fclose(logfd);

`system_flock()` Function

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

Syntax

int system_flock(SYS_FILE fd);

Return Values

The constant IO_OKAY if the lock succeeds, or the constant IO_ERROR if the lock fails.

Parameters

SYS_FILE fd is the platform-independent file descriptor.

`system_fopenRO()` Function

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

SYS_FILE system_fopenRO(char *path);

Return Values

The system-independent file descriptor (SYS_FILE) if the open succeeds, or 0 if the open fails.

Parameters

char *path is the file name.

`system_fopenRW()` Function

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 can be read and written by your program.

Syntax

SYS_FILE system_fopenRW(char *path);

Return Values

The system-independent file descriptor (SYS_FILE) if the open succeeds, or 0 if the open fails.

Parameters

char *path is the file name.

Example

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

`system_fopenWA()` Function

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 to which your program will append data.

Syntax

SYS_FILE system_fopenWA(char *path);

Return Values

The system-independent file descriptor (SYS_FILE) if the open succeeds, or 0 if the open fails.

Parameters

char *path is the file name.

`system_fread()` Function

The system_fread function reads a specified number of bytes from a specified file into a specified buffer. This function 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

int system_fread(SYS_FILE fd, char *buf, int sz);

Return Values

The number of bytes read, which might be less than the requested size if an error occurs, or if the end of the file was reached before that number of characters were 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.

`system_fwrite()` Function

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

int system_fwrite(SYS_FILE fd, char *buf, int sz);

Return Values

The constant IO_OKAY if the write succeeds, or the constant IO_ERROR if the write fails.

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.

`system_fwrite_atomic()` Function

The system_fwrite_atomic function writes a specified number of bytes from a specified buffer into a specified file. This 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.

Syntax

int system_fwrite_atomic(SYS_FILE fd, char *buf, int sz);

Return Values

The constant IO_OKAY if the write/lock succeeds, or the constant IO_ERROR if the write/lock fails.

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

SYS_FILE logfd;
char *logmsg = "An error occurred.";
system_fwrite_atomic(logfd, logmsg, strlen(logmsg));

`system_gmtime()` Function

The system_gmtime function is a thread-safe version of the standard gmtime function. This function returns the current time adjusted to Greenwich Mean Time.

Syntax

struct tm *system_gmtime(const time_t *tp, const struct tm *res);

Return Values

A pointer to a calendar time (tm) structure containing the GMT time. Depending on your system, the pointer might point to the data item represented by the second parameter, or the pointer might point to a staticallyallocated 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);

`system_localtime()` Function

The system_localtime function is a thread-safe version of the standard localtime function. This function returns the current time in the local time zone.

Syntax

struct tm *system_localtime(const time_t *tp, const struct tm *res);

Return Values

A pointer to a calendar time (tm) structure containing the local time. Depending on your system, the pointer might point to the data item represented by the second parameter, or the pointer might 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.

`system_lseek()` Function

The system_lseek function sets the file position of a file. This position affects where data from system_fread or system_fwrite is read or written.

Syntax

int system_lseek(SYS_FILE fd, int offset, int whence);

Return Values

The offset, in bytes, of the new position from the beginning of the file if the operation succeeds, or -1 if the operation fails.

Parameters

SYS_FILE fd is the platform-independent file descriptor.

int offset is a number of bytes relative to whence. This value may be negative.

int whence is 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_rename()` Function

The system_rename function renames a file. This function does not work on directories if the old and new directories are on different file systems.

Syntax

int system_rename(char *old, char *new);

Return Values

0 if the operation succeeds, or -1 if the operation fails.

Parameters

char *old is the old name of the file.

char *new is the new name for the file.

`system_ulock()` Function

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

Syntax

int system_ulock(SYS_FILE fd);

Return Values

The constant IO_OKAY if the operation succeeds, or the constant IO_ERROR if the operation fails.

Parameters

SYS_FILE fd is the platform-independent file descriptor.

`system_unix2local()` Function

The system_unix2local function converts a specified UNIX-style path name to a local file system path name. Use this function when you have a file name in the UNIX format such as one containing forward slashes, and you need to access a file on another system such as Windows. You can use system_unix2local to convert the UNIX file name into the format that Windows accepts. In the UNIX environment this function has no effect, but can be called for portability.

Syntax

char *system_unix2local(char *path, char *lp);

Return Values

A pointer to the local file system path string.

Parameters

char *path is the UNIX-style path name to be converted.

char *lp is the local path name.

You must allocate the parameter lp, which must contain enough space to hold the local path name.

`systhread_attach()` Function

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

Syntax

SYS_THREAD systhread_attach(void);

Return Values

A SYS_THREAD pointer to the platform-independent thread.

Parameters

None

`systhread_current()` Function

The systhread_current function returns a pointer to the current thread.

Syntax

SYS_THREAD systhread_current(void);

Return Values

A SYS_THREAD pointer to the current thread.

Parameters

None

`systhread_getdata()` Function

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

Syntax

void *systhread_getdata(int key);

Return Values

A pointer to the data that was earlier used with the systhread_setkey function from the current thread, using the same value of key if the call succeeds. Return Values NULL if the call does 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.

`systhread_newkey()` Function

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

int systhread_newkey(void);

Return Values

An integer key.

Parameters

None

`systhread_setdata()` Function

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

Syntax

void systhread_setdata(int key, void *data);

Return Values

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.

`systhread_sleep()` Function

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

Syntax

void systhread_sleep(int milliseconds);

Return Values

void

Parameters

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

`systhread_start()` Function

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

SYS_THREAD systhread_start(int prio, int stksz, void (*fn)(void *), void *arg);

Return Values

A new SYS_THREAD pointer if the call succeeds, or the constant SYS_THREAD_ERROR if the call does 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 (0), the function allocates a default size.

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

void *arg is the argument for the fn function.

`systhread_timerset()` Function

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

Note –

Because most systems do not allow the timer interval to be changed, this function should be considered a suggestion rather than a command.

Syntax

void systhread_timerset(int usec);

Return Values

void

Parameters

int usec is the time in microseconds

U

`USE_NSAPI_VERSION()` Macro

Plug-in developers can define the USE_NSAPI_VERSION macro before including the nsapi.h header file to request a particular version of NSAPI. The requested NSAPI version is encoded by multiplying the major version number by 100 and then adding the resulting value to the minor version number. For example, the following code requests NSAPI 3.2 features:

#define USE_NSAPI_VERSION 302 /* We want NSAPI 3.2 (Web Server 6.1) */
#include "nsapi.h"

To develop a plug-in that is compatible across multiple server versions, define USE_NSAPI_VERSION as the highest NSAPI version supported by all of the target server versions.

The following table lists server versions and the highest NSAPI version supported by each.

Table 6–2 NSAPI Versions Supported by Different Servers


Server Version	NSAPI Version
iPlanet Web Server 4.1	3.0
iPlanet Web Server 6.0	3.1
Netscape Enterprise Server 6.0	3.1
Netscape Enterprise Server 6.1	3.1
Sun ONE Application Server 7.0	3.1
Sun ONE Web Server 6.1	3.2
Sun Java System Web Proxy Server 4.0	3.3
Sun Java System Web Server 7.0 Update 1	3.3

Do not request a version of NSAPI higher than the highest version supported by the nsapi.h header that the plug-in is being compiled against. Additionally, to use USE_NSAPI_VERSION, you must compile against an nsapi.h header file that supports NSAPI 3.2 or higher.

Syntax

int USE_NSAPI_VERSION

Example

The following code can be used when building a plug-in designed to work with iPlanet Web Server 4.1 and Sun Java System Web Server 7.0 Update 1:

#define USE_NSAPI_VERSION 300 /* We want NSAPI 3.0 (Web Server 4.1) */
#include "nsapi.h"

`util_can_exec()` Function (UNIX Only)

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

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

Syntax

int util_can_exec(struct stat *finfo, uid_t uid, gid_t gid);

Return Values

1 if the file is executable, or 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 value determines the permissions of the UNIX user.

`util_chdir2path()` Function

The util_chdir2path function changes the current working directory. Because a server process can service multiple requests concurrently but has only a single current working directory, this function should not be used.

Syntax

int util_chdir2path(char *path);

Return Values

0 if the directory change succeeds, or -1 if the directory can not be changed.

Parameters

char *path is the name of a directory.

The parameter must be a writable string.

`util_cookie_find()` Function

The util_cookie_find function finds a specific cookie in a cookie string and returns its value.

Syntax

char *util_cookie_find(char *cookie, char *name);

Return Values

If successful, this function returns a pointer to the NULL-terminated value of the cookie. Otherwise, this function returns NULL. This function modifies the cookie string parameter by null-terminating the name and value.

Parameters

char *cookie is the value of the Cookie: request header.

char *name is the name of the cookie whose value is to be retrieved.

`util_env_find()` Function

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

Syntax

char *util_env_find(char **env, char *name);

Return Values

The value of the environment variable if the string is found, or NULL if the string was not found.

Parameters

char **env is the environment.

char *name is the name of an environment variable in env.

`util_env_create()` Function

The util_env_create function creates and allocates the environment specified by env and returns 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);

Return Values

A pointer to an environment.

Parameters

char **env is the 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.

`util_env_free()` Function

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

Syntax

void util_env_free(char **env);

Return Values

void

Parameters

char **env is the environment to be freed.

`util_env_replace()` Function

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

void util_env_replace(char **env, char *name, char *value);

Return Values

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.

`util_env_str()` Function

The util_env_str function creates an environment entry and returns the entry. This function does not check for non-alphanumeric symbols in the name, for example, the equal sign “=”. You can use this function to create a new environment entry.

Syntax

char *util_env_str(char *name, char *value);

Return Values

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.

`util_getline()` Function

The util_getline function scans the specified file buffer to find a line feed or carriage return/line feed terminated string. The string is copied into the specified buffer, and NULL-terminates it. The function returns a value that indicates whether the operation stored a string in the buffer, encountered an error, or reached the end of the file.

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

Syntax

int util_getline(filebuf *buf, int lineno, int maxlen, char *line);

Return Values

0 if successful, line contains the string.

1 if the end of file is reached, line contains the string.

-1 if an error occurs, line contains a description of the error.

Parameters

filebuf *buf is the file buffer to be scanned.

int lineno is used to include the line number in the error message when an error occurs. 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 in which to store the string. The user is responsible for allocating and deallocating line.

`util_hostname()` Function

The util_hostname function retrieves the local host name and returns it as a string. If the function cannot find a fullyqualified 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

char *util_hostname(void);

Return Values

A string containing the name, if a fullyqualified domain name is found. Otherwise, the function returns NULL.

Parameters

None

`util_is_mozilla()` Function

The util_is_mozilla function checks whether a specified user-agent header string is a Mozilla browser of at least a specified revision level. The function returns a 1 if the level matches, and 0 otherwise. This function uses strings to specify the revision level to avoid ambiguities such as 1.56 > 1.5.

Syntax

int util_is_mozilla(char *ua, char *major, char *minor);

Return Values

1 if the user-agent is a Mozilla browser, or 0 if the user-agent is not a Mozilla browser.

Parameters

char *ua is the user-agent string from the request headers.

char *major is the major release number, found to the left of the decimal point.

char *minor is the minor release number, found to the right of the decimal point.

`util_is_url()` Function

The util_is_url function checks whether a string is a URL, returns 1 if the string is a URL and 0 otherwise. The string is a URL if it begins with alphabetic characters followed by a colon (:).

Syntax

int util_is_url(char *url);

Return Values

1 if the string specified by url is a URL, or 0 if the string specified by url is not a URL.

Parameters

char *url is the string to be examined.

`util_itoa()` Function

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

int util_itoa(int i, char *a);

Return Values

The length of the string created.

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. The string should be at least 32 bytes long.

`util_later_than()` Function

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, RFC 850, and ctime formats.

Syntax

int util_later_than(struct tm *lms, char *ims);

Return Values

1 if the date represented by ims is the same as or later than that represented by the lms, or 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.

`util_sh_escape()` Function

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

The shell-special characters are the space plus the following characters:

&;`'"|*?~<>^()[]{}$\#!

Syntax

char *util_sh_escape(char *s);

Return Values

A newly allocated string.

Parameters

char *s is the string to be parsed.

`util_snprintf()` Function

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. This function returns the number of characters in the formatted buffer.

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

Syntax

int util_snprintf(char *s, int n, char *fmt, ...);

Return Values

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.

`util_sprintf()` Function

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

Because util_sprintf does not 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 runtime library of your compiler.

Syntax

int util_sprintf(char *s, char *fmt, ...);

Return Values

The number of characters formatted into the buffer.

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. The function does not handle any width or precision strings.

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

Example

char *logmsg;
int len;
logmsg = (char *) MALLOC(256);
len = util_sprintf(logmsg, "%s %s %s\n", ip, method, uri);

`util_strcasecmp()` Function

The util_strcasecmp function performs a comparison of two alphanumeric strings and returns a -1, 0, or 1 to signal which string is larger or the strings are identical.

The comparison is not casesensitive.

Syntax

int util_strcasecmp(const char *s1, const char *s2);

Return Values

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.

`util_strftime()` Function

The util_strftime function translates a tm structure, which is a structure describing a system time, into a textual representation. util_strftime is a thread-safe version of the standard strftime function.

Syntax

int util_strftime(char *s, const char *format, const struct tm *t);

Return Values

The number of characters placed into s, not counting the terminating NULL character.

Parameters

char *s is the string buffer to put the text into. This function does not perform bounds checking, so you must make sure that the buffer is large enough for the text of the date.

const char *format is a format string, similar to printf string in that it consists of text with certain %x substrings. You can use the constant HTTP_DATE_FMT to create date strings in the standard Internet format. For more information, see the documentation on the printf function for the runtime library of your compiler. For more information on time formats, see the Sun Java System Web Server 7.0 Update 1 Administrator’s Configuration File Reference.

const struct tm *t is a pointer to a calendar time (tm) structure, usually created by the function system_localtime or system_gmtime.

`util_strncasecmp()` Function

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 string is larger or that the strings are identical.

The function’s comparison is not case-sensitive.

Syntax

int util_strncasecmp(const char *s1, const char *s2, int n);

Return Values

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.

`util_uri_escape()` Function

The util_uri_escape function converts any special characters in the URI into the URI format. This format is %XX, where XX is the hexadecimal equivalent of the ASCII character. This function returns the escaped string. The special characters are %?#:+&*"<>, space, carriage return, and line feed.

Use util_uri_escape before sending a URI back to the client.

Syntax

char *util_uri_escape(char *d, char *s);

Return Values

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, if d is not NULL, it should be at least three times as large as the string s.

char *s is the string containing the original unescaped URI.

`util_uri_is_evil()` Function

The util_uri_is_evil function checks a specified URI for insecure path characters. Insecure path characters include //, /./, /../ and/., /.. (also for Windows./) at the end of the URI. Use this function to see whether a URI requested by the client is insecure.

Syntax

int util_uri_is_evil(char *t);

Return Values

1 if the URI is insecure, or 0 if the URI is secure.

Parameters

char *t is the URI to be checked.

`util_uri_parse()` Function

The util_uri_parse function converts //, /./, and /*/../ into / in the specified URI, where * is any character other than /. 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

void util_uri_parse(char *uri);

Return Values

void

Parameters

char *uri is the URI to be converted.

`util_uri_unescape()` Function

The util_uri_unescape function converts the encoded characters of a URI into their ASCII equivalents. Encoded characters appear as %XX, where XX is a hexadecimal equivalent of the character.

Note –

You cannot use an embedded null in a string, because NSAPI functions assume that a null is the end of the string. Therefore, passing Unicode-encoded content through an NSAPI plug-in does not work.

Syntax

void util_uri_unescape(char *uri);

Return Values

void

Parameters

char *uri is the URI to be converted.

`util_vsnprintf()` Function

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. This function returns the number of characters in the formatted buffer.

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

Syntax

int util_vsnprintf(char *s, int n, register char *fmt, va_list args);

Return Values

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.

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

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

`util_vsprintf()` Function

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

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

Syntax

int util_vsprintf(char *s, register char *fmt, va_list args);

Return Values

The number of characters formatted into the buffer.

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 argument variable obtained from a previous call to va_start.

V

`vs_alloc_slot()` Function

The vs_alloc_slot function allocates a new slot for storing a pointer to data specific to a certain VirtualServer*. The returned slot number can be used in subsequent vs_set_data and vs_get_data calls. The returned slot number is valid for any VirtualServer*.

The value of the pointer, which may be returned by a call to vs_set_data, defaults to NULL for every VirtualServer*.

Syntax

int vs_alloc_slot(void);

Return Values

A slot number if the function succeeds, or -1 if fails.

`vs_get_data()` Function

The vs_get_data function finds the value of a pointer to data for a given VirtualServer* and slot. The slot must be a slot number returned from vs_alloc_slot or vs_set_data.

Syntax

void* vs_get_data(const VirtualServer* vs, int slot);

Return Values

The value of the pointer previously stored using vs_set_data or NULL on failure.

Parameters

const VirtualServer* vs represents the virtual server to query the pointer for.

int slot is the slot number to retrieve the pointer from.

`vs_get_default_httpd_object()` Function

The vs_get_default_httpd_object function obtains a pointer to the default (or root) httpd_object from the virtual server's httpd_objset in the configuration defined by the obj.conf file of the virtual server class. The default object is typically named default. Plug-ins may only modify the httpd_object at VSInitFunc time. See vs_register_cb() Function for an explanation of VSInitFunc time.

Do not FREE the returned object.

Syntax

httpd_object* vs_get_default_httpd_object(VirtualServer* vs);

Return Values

A pointer the default httpd_object, or NULL on failure. Do not FREE this object.

Parameters

VirtualServer* vs represents the virtual server for which to find the default object.

`vs_get_doc_root()` Function

The vs_get_doc_root function finds the document root for a virtual server. The returned string is the full operating system path to the document root.

The caller should FREE the returned string when done with it.

Syntax

char* vs_get_doc_root(const VirtualServer* vs);

Return Values

A pointer to a string representing the full operating system path to the document root. The caller must FREE this string.

Parameters

const VirtualServer* vs represents the virtual server for which to find the document root.

`vs_get_httpd_objset()` Function

The vs_get_httpd_objset function obtains a pointer to the httpd_objset, the configuration defined by the obj.conf file of the virtual server class for a given virtual server. Plug-ins may only modify the httpd_objset at VSInitFunc time. See vs_register_cb() Function for an explanation of VSInitFunc time.

Do not FREE the returned objset.

Syntax

httpd_objset* vs_get_httpd_objset(VirtualServer* vs);

Return Values

A pointer to the httpd_objset, or NULL on failure. Do not FREE this objset.

Parameters

VirtualServer* vs represents the virtual server for which the function ID to find the objset.

`vs_get_id()` Function

The vs_get_id function finds the ID of a VirtualServer*.

The ID of a virtual server is a unique null-terminated string that remains constant across configurations. While IDs remain constant across configurations, the value of VirtualServer* pointers do not.

Do not FREE the virtual server ID string. If called during request processing, the string will remain valid for the duration of the current request. If called during VSInitFunc processing, the string will remain valid until after the corresponding VSDestroyFunc function has returned. For more information, see vs_register_cb() Function.

To retrieve a VirtualServer* that is valid only for the current request, use request_get_vs.

Syntax

const char* vs_get_id(const VirtualServer* vs);

Return Values

A pointer to a string representing the virtual server ID. Do not FREE this string.

Parameters

const VirtualServer* vs represents the virtual server of interest.

`vs_get_mime_type()` Function

The vs_get_mime_type function determines the MIME type that would be returned in the content-type: header for the given URI.

The caller should FREE the returned string when done with it.

Syntax

char* vs_get_mime_type(const VirtualServer* vs, const char* uri);

Return Values

A pointer to a string representing the MIME type. The caller must FREE this string.

Parameters

const VirtualServer* vs represents the virtual server of interest.

const char* uri is the URI whose MIME type is of interest.

`vs_lookup_config_var()` Function

The vs_lookup_config_var function finds the value of a configuration variable for a given virtual server.

Do not FREE the returned string.

Syntax

const char* vs_lookup_config_var(const VirtualServer* vs, const char* name);

Return Values

A pointer to a string representing the value of variable name on success, or NULL if variable name was not found. Do not FREE this string.

Parameters

const VirtualServer* vs represents the virtual server of interest.

const char* name is the name of the configuration variable.

`vs_register_cb()` Function

The vs_register_cb function enables a plug-in to register functions that will receive notifications of virtual server initialization and destruction events. The vs_register_cb function is typically called from an Init SAF in magnus.conf.

When a new configuration is loaded, all registered VSInitFunc (virtual server initialization) callbacks are called for each of the virtual servers before any requests are served from the new configuration. VSInitFunc callbacks are called in the same order they were registered. The first callback registered is the first callback called.

When the last request has been served from an old configuration, all registered VSDestroyFunc (virtual server destruction) callbacks are called for each of the virtual servers before any virtual servers are destroyed. VSDestroyFunc callbacks are called in reverse order. The first callback registered is the last callback called.

Either initfn or destroyfn may be NULL if the caller is not interested in callbacks for initialization or destruction, respectively.

Syntax

int vs_register_cb(VSInitFunc* initfn, VSDestroyFunc* destroyfn);

Return Values

The constant REQ_PROCEED if the operation succeeds.

The constant REQ_ABORTED if the operation fails.

Parameters

VSInitFunc* initfn is a pointer to the function to call at virtual server initialization time, or NULL if the caller is not interested in virtual server initialization events.

VSDestroyFunc* destroyfn is a pointer to the function to call at virtual server destruction time, or NULL if the caller is not interested in virtual server destruction events.

`vs_set_data()` Function

The vs_set_data function sets the value of a pointer to data for a given virtual server and slot. The *slot must be -1 or a slot number returned from vs_alloc_slot. If *slot is -1, vs_set_data calls vs_alloc_slot implicitly and returns the new slot number in *slot.

The stored pointer is maintained on a per-VirtualServer* basis, not a per-ID basis. Distinct VirtualServer*s from different configurations might exist simultaneously with the same virtual server IDs. However, because these configurations are distinct VirtualServer*s, each configuration has its own VirtualServer*-specific data. As a result, vs_set_data should generally not be called outside of VSInitFunc processing. See vs_register_cb() Function for an explanation of VSInitFunc processing.

Syntax

void* vs_set_data(const VirtualServer* vs, int* slot, void* data);

Return Values

Data on success, or NULL on failure.

Parameters

const VirtualServer* vs represents the virtual server to set the pointer for.

int* slot is the slot number at which to store the pointer.

void* data is the pointer to store.

`vs_translate_uri()` Function

The vs_translate_uri function translates a URI as though the URI were part of a request for a specific virtual server. The returned string is the full operating system path.

The caller should FREE the returned string when done with it.

Syntax

char* vs_translate_uri(const VirtualServer* vs, const char* uri);

Return Values

A pointer to a string representing the full operating system path for the given URI. The caller must FREE this string.

Parameters

const VirtualServer* vs represents the virtual server for which to translate the URI.

const char* uri is the URI to translate to an operating system path.

W

`write()` Function

The write filter method is called when output data is to be sent. Filters that modify or consume outgoing data should implement the write filter method.

Upon receiving control, a write implementation should first process the data as necessary, and then pass it on to the next filter layer, for example, by calling net_write(layer->lower, ...,). If the filter buffers outgoing data, it should implement the flush filter method.

Syntax

int write(FilterLayer *layer, const void *buf, int amount);

Return Values

The number of bytes consumed, which might be less than the requested amount if an error occurred.

Parameters

FilterLayer *layer is the filter layer in which the filter is installed.

const void *buf is the buffer that contains the outgoing data.

int amount is the number of bytes in the buffer.

Example

int myfilter_write(FilterLayer *layer, const void *buf, int amount)
{
    return net_write(layer->lower, buf, amount);
}

`writev()` Function

The writev filter method is called when multiple buffers of output data are to be sent. Filters that modify or consume outgoing data can implement the writev filter method.

If a filter implements the write filter method but not the writev filter method, the server automatically translates net_writev calls to net_write calls. As a result, filters for the outgoing data stream do not need to implement the writev filter method. However, for performance reasons, filters that implement the write filter method should also implement the writev filter method.

Syntax

int writev(FilterLayer *layer, const struct iovec *iov, int iov_size);

Return Values

The number of bytes consumed, which might be less than the requested amount if an error occurred.

Parameters

FilterLayer *layer is the filter layer the filter is installed in.

const struct iovec *iov is an array of iovec structures, each of which contains outgoing data.

int iov_size is the number of iovec structures in the iov array.

Example

int myfilter_writev(FilterLayer *layer, const struct iovec *iov, int iov_size)
{
    return net_writev(layer->lower, iov, iov_size);
}

Contained Within

Find More Documentation

Featured Support Resources

Chapter 6 NSAPI Function and Macro Reference

NSAPI Functions and Macros

C

CALLOC() Macro

Syntax

Return Values

Parameters

Example

See Also

cinfo_find() Function

Syntax

Returns

Parameters

condvar_init() Function

Syntax

Return Values

Parameters

See Also

condvar_notify() Function

Syntax

Return Values

Parameters

See Also

condvar_terminate() Function

Syntax

Return Values

Parameters

See Also

condvar_wait() Function

Syntax

Return Values

Parameters

See Also

crit_enter() Function

Syntax

Return Values

Parameters

See Also

crit_exit() Function

Syntax

Return Values

Parameters

See Also

crit_init() Function

Syntax

Return Values

Parameters

See Also

crit_terminate() Function

Syntax

Return Values

Parameters

See Also

D

daemon_atrestart() Function

Syntax

Return Values

Parameters

Example

F

filebuf_buf2sd() Function

Syntax

Return Values

Parameters

Example

See Also

filebuf_close() Function

Syntax

Return Values

Parameters

Example

See Also

filebuf_getc() Function

Syntax

Return Values

Parameters

See Also

`CALLOC()` Macro

`cinfo_find()` Function

`condvar_init()` Function

`condvar_notify()` Function

`condvar_terminate()` Function

`condvar_wait()` Function

`crit_enter()` Function

`crit_exit()` Function

`crit_init()` Function

`crit_terminate()` Function

`daemon_atrestart()` Function

`filebuf_buf2sd()` Function

`filebuf_close()` Function

`filebuf_getc()` Function

`filebuf_open()` Function

`filebuf_open_nostat()` Function

`filter_create()` Function

`filter_find()` Function

`filter_insert()` Function

`filter_layer()` Function

`filter_name()` Function

`filter_remove()` Function

`flush()` Function

`FREE()` Macro

`func_exec()` Function

`func_find()` Function

`func_insert()` Function

`insert()` Function