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

See Also

filebuf_close() Function, filebuf_open() Function, filebuf_open_nostat() Function, filebuf_getc() Function

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

See Also

filebuf_open() Function, filebuf_open_nostat() Function, filebuf_buf2sd() Function, filebuf_getc() Function

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.

See Also

filebuf_close() Function, filebuf_buf2sd() Function, filebuf_open() Function, filter_create() Function

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);
}

See Also

filebuf_getc() Function, filebuf_buf2sd() Function, filebuf_close() Function, filebuf_open_nostat() Function

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);
}

See Also

filebuf_close() Function, filebuf_open() Function, filebuf_getc() Function, filebuf_buf2sd() Function

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

See Also

filter_insert() Function, insert() Function, flush() Function, read() Function, sendfile() Function, write() Function, writev() Function, FilterMethods Data Structure

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.

See Also

filter_create() Function

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);
}

See Also

net_flush() Function, filter_create() Function

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

See Also

CALLOC() Macro, MALLOC() Macro, REALLOC() Macro, STRDUP() Macro, PERM_FREE() Macro

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.

See Also

log_error() Function

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

See Also

func_exec() Function

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

See Also

func_exec() Function, func_find() Function