F

                                                                                                                                                                                                                                                                                                                                      Back to [Book]     [Topic]

Functions and Macros beginning with F

The following functions are discussed in this section:

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.

int filebuf_buf2sd(filebuf *buf, SYS_NETFD sd);

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.

void filebuf_close(filebuf *buf);

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.

filebuf_getc(filebuf b);

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.

filebuf *filebuf_open(SYS_FILE fd, int sz);

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.

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

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

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.

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

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.

const Filter *filter_find(const char *name);

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.

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

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.

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

filter_name() Function

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

const char *filter_name(const Filter *filter);

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.

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

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

int flush(FilterLayer *layer);

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.

FREE(void *ptr);

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.

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

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.

FuncPtr func_find(char *name);

/* 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.

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

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

See Also

• func_exec() Function
• func_find() Function