cinfo_find base/cinfo.h
The cinfo_find function finds the content information for the Universal Resource Identifier (URI) and returns a pointer to a structure containing the information. Use this function to retrieve information on a URI or a local file name in order to tell the client the type of file it will be receiving from the server.
Syntax
#include </base/cinfo.h>
cinfo *cinfo_find(char *uri);
Returns
CINFO_SEPARATOR
(currently defined as a period).
#include <base/crit.h> CONDVAR condvar_init(CRITICAL id);
Note that pblock_nninsert requires that the parameter value be an
integer. If the value you assign is not a number, then instead use the
function pblock_nvinsert to create the parameter.
The name-value pairs in the string can have the format
Note that all back slashes () must be followed by a literal character. If
string values are found with no unescaped = signs (no name=), it assumes
the names 1, 2, 3, and so on, depending on the string position (zero doesn't
count). For example, if pblock_str2pblock finds
Note that the stat structure contains the information about the file you are
sending back to the client. The full description of the stat structure should
be available from the documentation for your system. For the basic
elements of the stat structure, see "The stat data structure" on page 195.
The sn and rq parameters can also be used to identify a specific request in
asynchronous operations, as well as for other internal housekeeping
purposes.
Note that the file name of the semaphore should be a file accessible to the
process.
Note that you must allocate the parameter lp, and that it must contain
enough space to hold the local pathname.
Note that the parameter must be a writable string because it isn't permanently modified.
Note that util_uri_escape does not check bounds for the parameter d.
Therefore, d should be at least three times as large as s.
Parameters
CRITICAL id is a critical-section variable.
See also
condvar_notify, condvar_terminate, condvar_wait, crit_init.
condvar_notify base/crit.h
The condvar_notify function is a critical-section function that awakens any threads that are blocked on the given critical-section variable. Use this function to awaken threads of execution of a given critical section. First, use crit_enter to gain ownership of the critical section. Then use the returned critical-section variable to call condvar_notify to awaken the threads. Finally, when condvar_notify returns, call crit_exit to surrender ownership of the critical section.
Syntax
#include <base/crit.h>
void condvar_notify(CONDVAR cv);
Returns
void
Parameters
CONDVAR cv is a condition variable.
See also
condvar_init, condvar_terminate, condvar_wait, crit_enter, crit_exit, crit_init.
condvar_terminate base/crit.h
Critical-section function that frees a condition variable. Use this function to free a previously allocated condition variable.
Warning
Terminating a condition variable that is in use can lead to unpredictable results.
Syntax
#include <base/crit.h>
void condvar_terminate(CONDVAR cv);
Returns
void
Parameters
CONDVAR cv is a condition variable.
See also
condvar_init, condvar_notify, condvar_wait, crit_init.
condvar_wait base/crit.h
Critical-section function that blocks on a given condition variable. Use this function to wait for a critical section (specified by a condition variable argument) to become available. The calling thread is blocked until another thread calls condvar_notify with the same condition variable argument. The caller must have entered the critical section associated with this condition variable before calling condvar_wait.
Syntax
#include <base/crit.h>
void condvar_wait(CONDVAR cv);
Parameters
CONDVAR cv is a condition variable.
Returns
void
See also
condvar_init, condvar_notify, condvar_terminate, crit_init.
crit_enter base/crit.h
Critical-section function that attempts to enter a critical section. Use this function to gain ownership of a critical section. If another thread already owns the section, the calling thread is blocked until the first thread surrenders ownership by calling crit_exit.
Syntax
#include <base/crit.h>
void crit_enter(CRITICAL crvar);
Returns
void
Parameters
CRITICAL crvar is a critical-section variable.
See also
crit_exit, crit_init, crit_terminate.
crit_exit base/crit.h
Critical-section function that surrenders ownership of a critical section. Use this function to surrender ownership of a critical section. If another thread is blocked waiting for the section, the block will be removed and the waiting thread will be given ownership of the section.
Syntax
#include <base/crit.h>
void crit_exit(CRITICAL crvar);
Returns
void
Parameters
CRITICAL crvar is a critical-section variable.
See also
crit_enter, crit_init, crit_terminate.
crit_init base/crit.h
Critical-section function that creates and returns a new critical-section variable (a variable of type CRITICAL). Use this function to obtain a new instance of a variable of type CRITICAL (a critical-section variable) to be used in managing the prevention of interference between two threads of execution. At the time of its creation, no thread owns the critical section.
Warning
Threads must not own or be waiting for the critical section when crit_terminate is called.
Syntax
#include <base/crit.h>
CRITICAL crit_init(void);
Parameters
No parameter is required.
Returns
A newly allocated critical-section variable (CRITICAL)
See also
crit_enter, crit_exit, crit_terminate.
crit_terminate base/crit.h
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
#include <base/crit.h>
void crit_terminate(CRITICAL crvar);
Returns
void
Parameters
CRITICAL crvar is a critical-section variable.
See also
crit_enter, crit_exit, crit_init.
daemon_atrestart netsite.h
The daemon_atrestart function lets you register a callback function named by fn to be used when the server receives a restart signal. Use this function when you need a callback function to deallocate resources allocated by an initialization function. The daemon_atrestart function is a generalization of the magnus_atrestart function.
Syntax
#include <netsite.h>
void daemon_atrestart(void (*fn)(void *), void *data);
Returns
void
Parameters
void (* fn) (void *) is the callback function.
void *data is the parameter passed to the callback function when the server is restarted.
Example
/* Close log file when server is restarted */
daemon_atrestart(brief_terminate, NULL);
return REQPROCEED;
See also
http_start_response.
filebuf_buf2sd base/buffer.h
The filebuf_buf2sd function sends a file buffer to a socket and returns the number of bytes sent.
Use this function to send the contents of a file to a server.
Syntax
#include <base/buffer.h>
int filebuf_buf2sd(filebuf *buf, SYS_NETFD sd);
Returns
Parameters
filebuf *buf is the name of the file buffer.
SYS_NETFD sd is the platform-independent identifier of the socket.
Example
if(filebuf_buf2sd(buf, sn->csd) == IO_ERROR)
ret = REQ_EXIT;
filebuf_close(buf);
See also
filebuf_close, filebuf_open, netbuf_buf2sd.
filebuf_close base/buffer.h
The filebuf_close function deallocates a file buffer and closes its associated files.
Generally, use filebuf_open to first open a file buffer, and then use filebuf_getc to access the information in the file. After you have finished using the file buffer, use filebuf_close to close it.
Syntax
#include <base/buffer.h>
void filebuf_close(filebuf *buf);
Returns
void
Parameters
filebuf *buf is the name of the file buffer.
Example
if(filebuf_buf2sd(buf, sn->csd) == IO_ERROR)
ret = REQ_EXIT;
filebuf_close(buf);
See also
filebuf_buf2sd, filebuf_getc, filebuf_open, netbuf_close
filebuf_getc base/buffer.h
The filebuf_getc function retrieves a character from the current cursor position and returns an integer.
Use filebuf_getc to sequentially read one character from the file buffer.
Syntax
#include <base/buffer.h>
netbuf_getc(netbuf b);
Returns
Parameters
netbuf b is the name of the file buffer.
See also
filebuf_close, netbuf_getc, netbuf_open
filebuf_open base/buffer.h
The filebuf_open function opens a new file buffer and returns a pointer to the buffer. Use this function to read through a file using a buffer. This provides more efficient file access because using the function guarantees use of buffered file I/O in environments where it is not supported by the operating system.
Syntax
#include <base/buffer.h>
filebuf *filebuf_open(SYS_FILE fd, int sz);
Returns
Parameters
SYS_FILE fd is the platform-independent file descriptor.
int sz is the size, in characters, to be used for the buffer.
Example
buf = filebuf_open(fd, &finfo);
if (!buf){
system_fclose(fd);
goto done;
}
See also
filebuf_close, filebuf_open_nostat, netbuf_open
filebuf_open_nostat base/buffer.h
The filebuf_open_nostat function opens a new file buffer and returns a new buffer structure. This function accomplishes the same purpose as the filebuf_open function, but is more efficient, because it does not need to call the stat function.
Syntax
#include <base/buffer.h>
#include <sys/stat.h>
filebuf* filebuf_open_nostat(SYS_FILE fd, int sz, struct stat *finfo);
Returns
Parameters
SYS_FILE fd is the platform-independent file descriptor.
int sz is the file descriptor to be opened.
struct stat *finfo is the file descriptor to be opened. Before calling the filebuf_open_nostat function, you must call the stat function for the file, so that the parameter returned by the stat function (specified by finfo) has been established.
Example
buf = filebuf_open_nostat(fd, FILE_BUFFERSIZE, &finfo);
if (!buf){
system_fclose(fd);
goto done;
}
See also
filebuf_close, filebuf_open
FREE netsite.h
The FREE macro is a platform-independent substitute for the C library routine free. It deallocates the space previously allocated by MALLOC or STRDUP to a specified pointer.
Syntax
#include <netsite.h>
FREE(ptr);
Returns
void
Parameters
ptr is a (void) pointer to an object. If the pointer is not one created by MALLOC or STRDUP, the behavior is undefined.
Example
if(alt) {
pb_param *pp = pblock_find("ppath", rq->vars);
/* Trash the old value */
FREE(pp->value);
/* Dup it because the library will later free this pblock */
pp->value = STRDUP(alt);
return REQ_PROCEED;
}
/* Else do nothing */
return REQ_NOACTION;
See also
MALLOC, REALLOC, STRDUP
func_exec frame/func.h
The func_exec function executes the function named by the fn entry in a specified parameter block, for a specified Session and a specified Request. If the function name is not found, the func_exec function creates a LOG_MISCONFIG
message for the missing function parameter.
You can use this function to execute a server application function (SAF) by identifying it in the parameter block.
Syntax
#include <frame/func.h>
int func_exec(pblock *pb, Session *sn, Request *rq);
Returns
REQ_ABORTED
if no function was executed
Parameters
pblock pb is the parameter block containing the function.
Session *sn identifies the Session structure.
Request *rq identifies the Request structure.
Note that the Session and Request parameters can be the same as the ones passed to your function.
See also
log_error
func_find frame/func.h
The func_find function returns a pointer to the function specified by name. If no pointer exists, the function returns NULL.
Syntax
#include <frame/func.h>
FuncPtr func_find(char *name);
Returns
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
log_error frame/log.h
The log_error function creates an entry in an error log, recording the date, the severity, and a specified text.
Syntax
#include <frame/log.h>
int log_error(int degree, char *func, Session *sn, Request *rq,
char *fmt, ...);
Returns
Parameters
int degree specifies the severity of the error. It must be one of the following constants:
LOG_WARN
--warning
LOG_MISCONFIG
--a syntax error or permission violation
LOG_SECURITY
--an authentication failure or 403 error from a host
LOG_FAILURE
--an internal problem
LOG_CATASTROPHE
--a non-recoverable server error
LOG_INFORM
--an informational message
Example
if(!groupbuf) {
log_error(LOG_WARN, "send-file", sn, rq,
"error opening buffer from %s (%s)"), path,
system_errmsg(fd));
return REQ_ABORTED;
}
See also
func_exec
magnus_atrestart netsite.h
Note
Please use the daemon-atrestart function in place of the obsolete
magnus_atrestart function.
The magnus_atrestart function lets you register a callback function named by fn to be used when the server receives a restart signal. Use this function when you need a callback function to deallocate resources allocated by an initialization function.
Syntax
#include <netsite.h>
void magnus_atrestart(void (*fn)(void *), void *data);
Returns
void
Parameters
void (* fn) (void *) is the callback function.
void *data is the parameter passed to the callback function when the server is restarted.
Example
/* Close log file when server is restarted */
magnus_atrestart(brief_terminate, NULL);
return REQPROCEED;
See also
http_start_response
MALLOC netsite.h
The MALLOC macro is a platform-independent substitute for the C library routine malloc. It uses memory pools, creating one for each request, automatically freeing it after the request has been processed. The data in the Request parameter block is allocated by MALLOC, not PERM_MALLOC which provides allocation that persists beyond the end of the request. If memory pooling has been disabled in the configuration file, PERM_MALLOC and MALLOC both obtain their memory from the system heap.
Syntax
#include <netsite.h>
MALLOC(size)
Returns
A pointer to space for an object of size size.
Parameters
size (an int) is the number of bytes to allocate.
Example
/* Initialize hosts array */
num_hosts = 0;
hosts = (char **) MALLOC(1 * sizeof(char *));
hosts[0] = NULL;
See also
PERM_MALLOC, REALLOC, FREE, PERM_FREE, STRDUP, PERM_STRDUP
net_ip2host base/net.h
The net_ip2host function transforms a textual IP address into a fully-qualified domain name and returns it.
Syntax
#include <base/net.h>
char *net_ip2host(char *ip, int verify);
Returns
Parameters
char *ip is the IP (Internet Protocol) address as a character string in dotted-decimal notation: nnn.nnn.nnn.nnn
int verify, if non-zero, specifies that the function should verify the fully-qualified domain name. Though this requires an extra query, you should use it when determining access control.
net_read base/net.h
The net_read function reads bytes from a specified socket into a specified buffer. The function waits to receive data from the socket until either at least one byte is available in the socket or the specified time has elapsed.
Syntax
#include <base/net.h
int net_read (SYS_NETFD sd, char *buf, int sz, int timeout);
Returns
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. Note that the purpose of timeout is not to return because not enough bytes were read in the given time, but to limit the amount of time devoted to waiting until some data arrives.
See also
net_socket, net_write
net_socket base/net.h
The net_socket function opens a connection to a socket, creating a new socket descriptor. The socket is not connected to anything, and is not listening to any port. A function must use net_connect to make a connection, and net_accept to listen.
Syntax
#include <base/net.h>
SYS_NETFD net_socket (int domain, int type, int protocol);
Returns
The platform-independent socket descriptor (SYS_NETFD) associated with the socket.
Parameters
int domain must be the constant AF_INET
.
int type must be the constant SOCK_STREAM
.
int protocol must be the constant IPPROTO_TCP
.
See also
net_read, net_write
net_write base/net.h
The net_write function writes a specified number of bytes to a specified socket from a specified buffer. It returns the number of bytes written.
Syntax
#include <base/net.h>
int net_write (SYS_NETFD sd, char *buf, int sz);
Returns
The number of bytes written, which may be less than the requested size if an error occurred.
Parameters
SYS_NETFD sd is the platform-independent socket descriptor.
char *buf is the buffer containing the bytes.
int sz is the number of bytes to write.
Example
/* Start response by giving boundary string */
if(net_write(sn->csd, FIRSTMSG, strlen(FIRSTMSG)) == IO_ERROR)
return REQ_EXIT;
See also
net_socket, net_write
netbuf_buf2sd base/buffer.h
The netbuf_buf2sd function sends a buffer to a socket. You can use this function to send data from IPC pipes to the client.
Syntax
#include <base/buffer.h>
int netbuf_buf2sd(netbuf *buf, SYSNETFD sd, int len);
Returns
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.
See also
filebuf_buf2sd, netbuf_close, netbuf_grab, netbuf_open
netbuf_close base/buffer.h
The netbuf_close function deallocates a network buffer and closes its associated files. Use this function when you need to deallocate the network buffer and close the socket.
Note that you should never close the netbuf parameter in a Session structure.
Syntax
#include <base/buffer.h>
void netbuf_close(netbuf *buf);
Returns
void
Parameters
netbuf *buf is the buffer to close.
See also
filebuf_close, netbuf_grab, netbuf_open
netbuf_getc base/buffer.h
The netbuf_getc function retrieves a character from the cursor position of the network buffer specified by b.
Syntax
#include <base/buffer.h>
netbuf_getc(netbuf b);
Returns
IO_EOF
or IO_ERROR
, for end of file or error
Parameters
netbuf b is the buffer from which to retrieve one character.
See also
filebuf_getc, netbuf_grab, netbuf_open
netbuf_grab base/buffer.h
The netbuf_grab function assigns a size to the array in the network buffer named by buf. The size of the array is specified by sz, which is the number of bytes from the buffer's associated object.
Note that the buffer processes the allocation and deallocation of the array.
This function is used by the function netbuf_buf2sd.
Syntax
#include <base/buffer.h>
int netbuf_grab(netbuf *buf, int sz);
Returns
IO_EOF
or IO_ERROR
, for end of file or error
Parameters
netbuf *buf is the buffer to read into.
int sz is the array size for the buffer to allocate.
See also
netbuf_close, netbuf_open
netbuf_open base/buffer.h
The netbuf_open function opens a new network buffer and returns it. You can use netbuf_open to create a netbuf structure and start using buffered I/O on a socket.
Syntax
#include <base/buffer.h>
netbuf* netbuf_open(SYS_NETFD sd, int sz);
Returns
A new netbuf structure (network buffer)
Parameters
SYS_NETFD sd is the platform-independent identifier of the socket.
int sz is the number of characters to allocate for the network buffer.
See also
filebuf_open, netbuf_close, netbuf_grab
param_create base/pblock.h
The param_create function creates a parameter block structure containing a specified name and value. If the name or value is not NULL, the pair are copied and placed into the new parameter block structure; otherwise the pair is created with name and value both. Use this function to prepare a parameter block structure to be used in calls to parameter block routines such as pblock_pinsert.
Syntax
#include <base/pblock.h>
pb_param *param_create(char *name, char *value);
Returns
A new parameter block structure.
Parameters
char *name is the string containing the name portion of the name-value pair.
char *value is the string containing the value portion of the name-value pair.
Example
pblock *pb = pblock_create(4);
pb_param *newpp = param_create("hello","world");
pblock_pinsert(newpp, pb);
See also
param_free
param_free base/pblock.h
The param_free function frees the parameter specified by pp. Use the param_free function for error checking after removing the function using pblock_remove.
Syntax
#include <base/pblock.h>
int param_free(pb_param *pp);
Returns
Parameters
pb_param *pp is the name portion of a name-value pair stored in a pblock.
Example
int check(pblock *pb)
{
if(param_free(pblock_remove("hello", pb)))
return 1; /* signal that we removed it */
else
return 0; /* We didn't remove it. */
}
See also
param_create, pblock_remove
pblock_copy base/pblock.h
The pblock_copy function copies the contents of one parameter block into another.
Syntax
#include <base/pblock.h>
void pblock_copy(pblock *src, pblock *dst);
Returns
void
Parameters
pblock *src is the source parameter block
pblock *dst is the destination parameter block.
Both entries are newly allocated so that the original parameter block may be freed, or the new parameter block changed, without affecting the other parameter block.
See also
pblock_create, pblock_dup, pblock_free, pblock_find, pblock_remove, pblock_nvinsert
pblock_create base/pblock.h
The pblock_create function creates a new parameter block. The system maintains an internal hash table for fast name-value pair lookups.
Syntax
#include <base/pblock.h>
pblock *pblock_create(int n);
Returns
The newly allocated parameter block.
Parameters
int n is the size of the hash table (number of name-value pairs) for the parameter block.
See also
pblock_copy, pblock_dup, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock
pblock_dup base/pblock.h
The pblock_dup function duplicates a parameter block. It is equivalent to a sequence of pblock_create and pblock_copy.
Syntax
#include <base/pblock.h>
pblock pblock_dup(pblock *src);
Returns
The newly allocated parameter block.
Parameters
pblock *src is the source parameter block
See also
pblock_create, pblock_free, pblock_find, pblock_remove, pblock_nvinsert
pblock_find base/pblock.h
The pblock_find function finds a specified name-value pair entry in a parameter block, and retrieves the name and structure of the parameter block. If you only want the value of the parameter block, use only the function pblock_findval to get the actual value in the name-value pair.
Note that this is implemented as a macro.
Syntax
#include <base/pblock.h>
pb_param *pblock_find(char *name, pblock *pb);
Returns
Parameters
char *name is the name of a name-value pair.
pblock *pb is the parameter block to be searched.
See also
pblock_copy, pblock_findval, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock
pblock_findval base/pblock.h
The pblock_findval function finds a specified name-value pair entry in a parameter block. Use pblock_findval if you want to retrieve the name, structure, and value of the parameter block. However, if you just want the name and structure of the parameter block, use only the macro pblock_find.
Syntax
#include <base/pblock.h>
char *pblock_findval(char *name, pblock *pb);
Returns
Parameters
char *name is the name of a name-value pair.
pblock *pb is the parameter block to be searched.
Example
see pblock_nvinsert.
See also
pblock_copy, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock
pblock_free base/pblock.h
The pblock_free function frees a specified parameter block and any entries inside it. If you want to save a variable in the parameter block, remove the variable using the function pblock_remove and then save the resulting pointer.
Syntax
#include <base/pblock.h>
void pblock_free(pblock *pb);
Returns
void
Parameters
pblock *pb is the parameter block to be freed.
See also
pblock_copy, pblock_create, pblock_find, pblock_nvinsert, pblock_remove, pblock_str2pblock
pblock_nninsert base/pblock.h
The pblock_nninsert function creates a new parameter structure with a given name and a numeric value, and inserts it into a specified parameter block. The name and value parameters are also newly allocated.
Syntax
#include <base/pblock.h>
pb_param *pblick_nninsert(char *name, int value, pblock *pb);
Returns
The new parameter block structure
Parameters
char *name is the name by which the name-value pair is stored.
int value is the numeric value being inserted into the parameter block
See also
pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock
pblock_nvinsert base/pblock.h
The pblock_nvinsert function creates a new parameter structure with a given name and character value, and inserts it into a specified parameter block. The name and value parameters are also newly allocated.
You could use this function when an error condition is encountered, in order to insert an error into the parameter block argument and to tell initialization routines in the server that an error occurred.
Syntax
#include <base/pblock.h>
pb_param *pblock_nvinsert(char *name, char *value, pblock *pb);
Returns
The newly allocated parameter block structure
Parameters
char *name is the name by which the name-value pair is stored.
char *value is the string value being inserted into the parameter block.
pblock *pb is the parameter block into which the insertion occurs.
Example
int brief_init(pblock *pb, Session *sn, Request *rq)
{
/* find "find" value in the parameter blcock */
char *fn = pblock_findval("file", pb);
/* if "file" is not found, insert an "error" value
asking to supply a file name*/
if(!fn) {
pblock_nvinsert("error",
"brief-init: please supply a file name", pb);
return REQ_ABORTED;
}
/* open a file in write/append mode*/
logfd = system_fopenWA(fn);
if(logfd == SYS_ERROR_FD) {
pblock_nvinsert("error",
"brief-init: please supply a file name", pb);
return REQ_ABORTED;
}
See also
pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nninsert, pblock_remove, pblock_str2pblock
pblock_pb2env base/pblock.h
The pblock_pb2env function copies a specified parameter block into a specified environment. The function creates one new environment entry for each name-value pair in the parameter block. Use this function to send pblock entries to a program that you are going to execute.
Syntax
#include <base/pblock.h>
char **pblock_pb2env(pblock *pb, char **env);
Returns
A pointer to the array of name-value pairs.
Parameters
pblock *pb is the parameter block to be copied.
char **env is the environment into which the parameter block is to be copied.
See also
pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock
pblock_pblock2str base/pblock.h
The pblock_pblock2str function copies all parameters of a specified parameter block into a specified string. The function allocates additional non-heap space for the string if needed.
Use this function to stream the parameter block for archival and other purposes.
Syntax
#include <base/pblock.h>
char *pblock_pblock2str(pblock *pb, char *str);
Returns
The new version of the str parameter. If str was NULL, this is a new string; otherwise it is a reallocated string. In either case, it is allocated in the pool of memory established for the current request.
Parameters
pblock *pb is the parameter block to be copied.
char *str is the string into which the parameter block is to be copied. It must have been allocated by MALLOC or REALLOC, not by PERM_MALLOC or PERM_REALLOC (which allocate from the heap).
Each name-value pair in the string is separated from its neighbor pair by a space and is in the format name="value"
.
See also
pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock
pblock_pinsert base/pblock.h
This function can be used instead of the function pblock_nvinsert. Both functions insert an error into the parameter block argument to tell initialization routines in the server that an error occurred. However pblock_pinsert is more convenient if you want to insert several parameter structures.
Syntax
#include <base/pblock.h>
void pblock_pinsert(pb_param *pp, pblock *pb);
Returns
void
Parameters
pb_param *pp is the parameter to insert.
pblock *pb is the parameter block.
See also
pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_str2pblock
pblock_remove base/pblock.h
The pblock_remove function removes a specified name-value entry from a specified parameter block.
Note that this function is implemented as a macro. Furthermore, if you use this macro your code must eventually call param_free in order to deallocate the memory used by the parameter structure.
Syntax
#include <base/pblock.h>
pb_param *pblock_remove(char *name, pblock *pb);
Returns
Parameters
char *name is the name portion that identifies the name-value pair to be removed.
pblock *pb is the parameter block from which the name-value entry is to be removed.
Example
see pblock_free.
See also
pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_str2pblock
pblock_str2pblock base/pblock.h
The pblock_str2pblock function scans a string for parameter pairs, adds the value to a parameter block, and returns the number of parameters added.
Syntax
#include <base/pblock.h>
int pblock_str2pblock(char *str, pblock *pb);
Returns
Parameters
char *str is the string to be scanned.
name=value
or
name="value"
.
"some"
"strings"
"together"
, the function treats the strings as if they appeared in the
name-value pairs as 1="some"
2 ="strings" 3="together"
.
See also
pblock_copy, pblock_create, pblock_find, pblock_free, pblock_nvinsert, pblock_remove, pblock_pblock2str
PERM_FREE netsite.h
The PERM_FREE macro is a platform-independent substitute for the C library routine free. It deallocates the persistent space previously allocated by PERM_MALLOC or PERM_STRDUP to a specified pointer. If memory pooling has been disabled in the configuration file, PERM_FREE and FREE both return memory to the system heap.
Syntax
#include <netsite.h>
PERM_FREE(ptr);
Returns
void
Parameters
ptr is a (void) pointer to an object. If the pointer is not one created by PERM_MALLOC or PERM_STRDUP, the behavior is undefined.
See also
FREE, MALLOC, REALLOC, STRDUP, PERM_MALLOC, PERM_STRTUP
PERM_MALLOC netsite.h
The PERM_MALLOC macro is a platform-independent substitute for the C library routine malloc. It provides allocation of memory that persists after the request that was being processed has been completed. If memory pooling has been disabled in the configuration file, PERM_MALLOC and MALLOC both obtain their memory from the system heap.
Syntax
#include <netsite.h>
PERM_MALLOC(size)
Returns
A pointer to space for an object of size size
Parameters
size (an int) is the number of bytes to allocate.
Example
/* Initialize hosts array */
num_hosts = 0;
hosts = (char **) PERM_MALLOC(1 * sizeof(char *));
hosts[0] = NULL;
See also
MALLOC, REALLOC, FREE, PERM_FREE, STRDUP, PERM_STRDUP
PERM_STRDUP netsite.h
The PERM_STRDUP macro is a platform-independent substitute for the common Unix library routine strdup. It creates a new copy of a string in memory that persists after the request that was being processed has been completed. If memory pooling has been disabled in the configuration file, PERM_STRDUP and STRDUP both obtain their memory from the system heap.
The strdup routine is functionally equivalent to
char *newstr = (char *) malloc(strlen(str) + 1);
strcpy(newstr, str);
Syntax
#include <netsite.h>
PERM_STRDUP(ptr);
Returns
A pointer to the new string
Parameters
ptr is a pointer to a string.
See also
MALLOC, FREE, REALLOC
protocol_dump822 frame/protocol.h
The protocol_dump822 function prints headers from a specified parameter block into a specific buffer, with a specified size and position. Use this function to serialize the headers so that they can be sent, for example, in a mail message.
Syntax
#include <frame/protocol.h>
char *protocol_dump822(pblock *pb, char *t, int *pos, int tsz);
Returns
The buffer, reallocated if necessary
The function also modifies pos to denote a new position in the buffer.
Parameters
pblock *pb is the parameter block structure.
char *t is the name of the buffer.
int *pos is the position within the buffer at which the headers are to be inserted.
int *tsz is the size of the buffer.
See also
protocol_handle_session, protocol_scan_headers, protocol_start_response, protocol_status
protocol_set_finfo frame/protocol.h
The protocol_set_finfo function retrieves the content-length and last-modified date from a specified stat structure, for a specified session and the request generated by that session. Use protocol_set_finfo only after receiving a start_response from a Service-class server application function (SAF).
Syntax
#include <frame/protocol.h>
int protocol_set_finfo(Session *sn, Request *rq, struct stat *finfo);
Returns
REQ_PROCEED
if the request can proceed normally
REQ_ABORTED
if the function should treat the request normally, but not send any output to the client
Parameters
Session *sn is the session that generated the request.
Request *rq is the request.
stat *finfo is the stat structure for the file.
See also
protocol_handle_session, protocol_scan_headers, protocol_start_response, protocol_status
protocol_start_response frame/protocol.h
The protocol_start_response function initiates the HTTP response for a specified session and request. If the protocol version is HTTP/0.9, the function does nothing, because that version has no concept of status. If the protocol version is HTTP/1.0, the function sends a status line followed by the response headers. Use this function to set up HTTP and prepare the client and server to receive the body (or data) of the response.
Syntax
#include <frame/protocol.h>
int protocol_start_response(Session *sn, Request *rq);
Returns
REQ_PROCEED
if the operation succeeded, in which case you can send the data you were preparing to send
REQ_NOACTION
if the operation succeeded, but the client has requested that the server not send the data because the client has it in cache
REQ_ABORTED
if the operation did not succeed
Parameters
Session *sn is the session that generated the request.
Request *rq is the request to which a response is being started.
Example
/* A noaction response from this function means the request was HEAD */
if(protocol_start_response(sn, rq) == REQ_NOACTION) {
filebuf_close(groupbuf); /* this also closes fd */
return REQ_PROCEED;
}
See also
protocol_handle_session, protocol_scan_headers, protocol_status
protocol_status frame/protocol.h
The protocol_status function sets the session status to indicate whether an error condition occurred. If the reason string is NULL, the server attempts to find a reason string for the given status code. If it finds none, it returns "Unknown reason."
This reason string is sent to the client in the status line. Use this function to set the status of the session before calling the function protocol_start_response.
The following is a list of valid status codes:
PROTOCOL_OK
PROTOCOL_NO_RESPONSE
PROTOCOL_REDIRECT
PROTOCOL_NOT_MODIFIED
PROTOCOL_BAD_REQUEST
PROTOCOL_UNAUTHORIZED
PROTOCOL_FORBIDDEN
PROTOCOL_NOT_FOUND
PROTOCOL_PROXY_UNAUTHORIZED
PROTOCOL_SERVER_ERROR
PROTOCOL_NOT_IMPLEMENTED
Syntax
#include <frame/protocol.h>
void protocol_status(Session *sn, Request *rq, int n, char *r);
Returns
void
, but it sets values in the Session/Request designated by sn/rq for the status code and the reason string
Parameters
Session *sn is the session that generated the request.
Request *rq is the request that is being checked on.
int n is the value to set the status code to.
char *r is the reason string.
Example
if( (t = pblock_findval("path-info", rq->vars)) ) {
protocol_status(sn, rq, PROTOCOL_NOT_FOUND, NULL);
log_error(LOG_WARN, "send-images", sn, rq,
"%s%s not found", path, t);
return REQ_ABORTED;
}
See also
protocol_handle_session, protocol_scan_headers, protocol_start_response
protocol_uri2url frame/protocol.h
The protocol_uri2url function takes strings containing the given URI prefix and URI suffix, and creates a newly-allocated fully qualified URL in the form http://(server):(port)(prefix)(suffix).
If you want to omit either the URI prefix or suffix, use "" instead of NULL as the value for either parameter. To redirect the client somewhere else, use the function pblock_nvinsert to create a new entry in the vars pblock in your Request structure.
Syntax
#include <frame/protocol.h>
char *protocol_uri2url(char *prefix, char *suffix);
Returns
A new string containing the URL
Parameters
char *prefix is the prefix.
char *suffix is the suffix.
See also
protocol_handle_session, protocol_scan_headers, protocol_start_response, protocol_status
protocol_uri2url_dynamic frame/protocol.h
The protocol_uri2url function takes strings containing the given URI prefix and URI suffix, and creates a newly-allocated fully qualified URL in the form http://(server):(port)(prefix)(suffix).
If you want to omit either the URI prefix or suffix, use "" instead of NULL as the value for either parameter. To redirect the client somewhere else, use the function pblock_nvinsert to create a new entry in the vars in the pblock in your Request structure.
The protocol_uri2url_dynamic function is exactly like the protocol_uri2url function but should be used whenever the Session and Request structures are available. This ensures that the URL that it constructs refers to the host that the client specified.
Syntax
#include <frame/protocol.h>
char *protocol_uri2url(char *prefix, char *suffix, Session *sn,
Request *rq);
Returns
A new string containing the URL
Parameters
char *prefix is the prefix.
char *suffix is the suffix.
Session *sn is the session that generated the request.
Request *rq is the request that is being processed.
See also
protocol_handle_session, protocol_scan_headers, protocol_start_response, protocol_status, protocol_uri2url_dynamic
REALLOC netsite.h
The REALLOC macro is a platform-independent substitute for the C library routine realloc. It changes the size of a specified object that was originally created by MALLOC or STRDUP. The contents of the object remain unchanged up to the minimum of the old and new sizes. If the new size is larger, the new space is uninitialized.
WARNING
Calling REALLOC for a block that was allocated with PERM_MALLOC will not work.
Syntax
#include <netsite.h>
REALLOC(ptr, size);
Returns
A pointer to the new space if the request could be satisfied.
Parameters
ptr is a (void) pointer to an object. If the pointer is not one created by MALLOC or STRDUP, the behavior is undefined.
size (an int) is the number of bytes to allocate.
Example
while(fgets(buf, MAX_ACF_LINE, f)) {
/* Blast linefeed that stdio leaves on there */
uf[strlen(buf) - 1] = '0';
hosts = (char **) REALLOC(hosts, (num_hosts + 2) * sizeof(char *));
hosts[num_hosts++] = STRDUP(buf);
hosts[num_hosts] = NULL;
}
See also
MALLOC, FREE, STRDUP
request_create frame/req.h
Utility function that creates a new request structure.
Syntax
#include <frame/req.h>
Request *request_create(void);
Returns
A Request structure
Parameters
No parameter is required.
See also
request_free, request_header
request_free frame/req.h
The request_free function frees a specified request structure.
Syntax
#include <frame/req.h>
void request_free(Request *req);
Returns
void
Parameters
Request *rq is the request structure to be freed.
See also
request_header
request_header frame/req.h
The request_header function finds the parameter block containing the client's HTTP headers. You can use this function to access a parameter block indirectly, thereby avoiding multiple and unnecessary calls. In addition, request_header allows you to access the parameter block headers in your copy of the request structure.
Syntax
#include <frame/req.h>
int request_header(char *name, char **value, Session *sn, Request *rq);
Returns
A REQ return code, such as REQ_ABORTED
to signal that an error occurred or REQ_PROCEED
to signal that all went well
Parameters
char *name is the name of the header.
char **value is the address where the function will place the value of the specified header. If none is found, the function stores a NULL.
Session *sn is the session identifier for the server application function call that generated the request.
Request *rq is the request identifier for a server application function call.
Example
see shexp_cmp
See also
request_create, request_free
request_stat_path frame/req.h
The request_stat_path function returns the file information structure for a specified path, if none is specified, the path
entry in the vars
pblock in a specified Request structure. If the resulting file name points to a file that the server can read, request_stat_path returns a new file information structure. This structure contains information on the size of the file, when it was last accessed, and when it was last changed.
You can use request_stat_path to retrieve information on the file you are currently accessing (instead of calling stat directly), because this function keeps track of other calls.
Syntax
#include <frame/req.h>
struct stat *request_stat_path(char *path, Request *rq);
Returns
Parameters
char *path is the string containing the name of the path. If the value of path is NULL, the function uses the path
entry in the vars
pblock in the Request structure denoted by rq.
Request *rq is the request identifier for a server application function call.
Example
if( (!(fi = request_stat_path(path, rq)) ) ||
( (fd = system_fopenRO(path)) == IO_ERROR) )
...
See also
request_create, request_free, request_header
request_translate_uri frame/req.h
The request_translate_uri function performs virtual to physical mapping on a specified URI during a specified session. Use this function when you want to determine which file would be sent back if a given URI is accessed.
Syntax
#include <frame/req.h>
char *request_translate_uri(char *uri, Session *sn);
Returns
Parameters
char *uri is the name of the URI.
Session *sn is the session identifier for the server application function call.
See also
request_create, request_free, request_header
sem_grab base/sem.h
The sem_grab function requests exclusive access to a specified semaphore. If exclusive access is unavailable, the caller blocks execution until exclusive access becomes available. Use this function to ensure that only one server processor thread performs an action at a time.
Syntax
#include <base/sem.h>
int sem_grab(SEMAPHORE id);
Returns
Parameters
SEMAPHORE id is the unique identification number of the requested semaphore.
See also
sem_init, sem_release, sem_terminate, sem_tgrab
sem_init base/sem.h
The sem_init function creates a semaphore with a specified name and unique identification number. Use this function to allocate a new semaphore that will be used with the functions sem_grab and sem_release. Call sem_init from an init class function to initialize a static or global variable that the other classes will later use.
Syntax
#include <base/sem.h>
SEMAPHORE sem_init(char *name, int number);
Returns
The constant SEM_ERROR if an error occurred.
Parameters
SEMAPHORE *name is the name for the requested semaphore.
See also
sem_grab, sem_release, sem_terminate
sem_release base/sem.h
The sem_release function releases the process's exclusive control over a specified semaphore. Use this function to release exclusive control over a semaphore created with the function sem_grab.
Syntax
#include <base/sem.h>
int sem_release(SEMAPHORE id);
Returns
Parameters
SEMAPHORE id is the unique identification number of the semaphore.
See also
sem_grab, sem_init, sem_terminate
sem_terminate base/sem.h
The sem_terminate function deallocates the semaphore specified by id. You can use this function to deallocate a semaphore that was previously allocated with the function sem_init.
Syntax
#include <base/sem.h>
void sem_terminate(SEMAPHORE id);
Returns
void
Parameters
SEMAPHORE id is the unique identification number of the semaphore.
See also
sem_grab, sem_init, sem_release
sem_tgrab base/sem.h
The sem_tgrab function tests and requests exclusive use of a semaphore. Unlike the somewhat similar sem_grab function, if exclusive access is unavailable the caller is not blocked, but receives a return value of -1. Use this function to ensure that only one server processor thread performs an action at a time.
Syntax
#include <base/sem.h>
int sem_grab(SEMAPHORE id);
Returns
Parameters
SEMAPHORE id is the unique identification number of the semaphore.
See also
sem_grab, sem_init, sem_release, sem_terminate
session_create base/session.h
The session_create function creates a new Session structure for the client with a specified socket descriptor and a specified socket address. It returns a pointer to that structure.
Syntax
#include <base/session.h>
Session *session_create(SYS_NETFD csd, struct sockaddr_in *sac);
Returns
Parameters
SYS_NETFD csd is the platform-independent socket descriptor.
sockaddr_in *sac is the socket address.
See also
session_create, session_maxdns
session_free base/session.h
The session_free function frees a specified Session structure. Note that session_free does not close the client socket descriptor associated with the session.
Syntax
#include <base/session.h>
void session_free(Session *sn);
Returns
void
Parameters
Session *sn is the Session to be freed.
See also
session_create, session_maxdns
session_maxdns base/session.h
The session_maxdns function resolves the IP address of the client associated with a specified session into a host name. It returns a string. You can use session_maxdns to change the numeric IP address into something more readable. Use session_maxdns instead of the function session_dns if you want to be sure that the host name is associated with the IP address of the client.
This function is implemented as a macro.
Syntax
#include <base/session.h>
char *session_maxdns(Session *sn);
Returns
Parameters
Session *sn is the session identifier for the server application function call.
shexp_casecmp base/shexp.h
The shexp_casecmp function validates a specified shell expression and compares it with a specified string. It returns one of three possible values representing match, no match, and invalid comparison. Note that (in contrast with the shexp_cmp function) the comparison is not case-sensitive.
Use this function if you have a shell expression like *.netscape.com
and you want to make sure that a string matches it, such as foo.netscape.com
.
Syntax
#include <base/shexp.h>
int shexp_casecmp(char *str, char *exp);
Returns
Parameters
char *str is the string to be compared.
char *exp is the shell expression (possibly containing wildcard characters) to compare against.
See also
shexp_cmp, shexp_match
shexp_cmp base/shexp.h
The shexp_casecmp function validates a specified shell expression and compares it with a specified string. It returns one of three possible values representing match, no match, and invalid comparison. Note that (in contrast with the shexp_casecmp function) the comparison is case-sensitive.
Use this function if you have a shell expression like *.netscape.com
and you want to make sure that a string matches it, such as foo.netscape.com
.
Syntax
#include <base/shexp.h>
int shexp_cmp(char *str, char *exp);
Returns
Parameters
char *str is the string to be compared.
char *exp is the shell expression (possibly containing wildcard characters) to compare against.
Example
#include "base/util.h" /* is_mozilla */
#include "frame/protocol.h" /* protocol_status */
#include "base/shexp.h" /* shexp_cmp */
int https_redirect(pblock *pb, Session *sn, Request *rq)
{
/* Server Variable */
char *ppath = pblock_findval("ppath", rq->vars);
/* Parameters */
char *from = pblock_findval("from", pb);
char *url = pblock_findval("url", pb);
char *alt = pblock_findval("alt", pb);
/* Work vars */
/* Check usage */
if((!from) || (!url)) {
log_error(LOG_MISCONFIG, "https-redirect", sn, rq,
"missing parameter (need from, url)");
return REQ_ABORTED;
}
/* Use wildcard match to see if this path is one to redirect */
if(shexp_cmp(ppath, from) != 0)
return REQ_NOACTION; /* no match */
/* The only way to check for SSL capability is to check UA */
if(request_header("user-agent", &ua, sn, rq) == REQ_ABORTED)
return REQ_ABORTED;
/* The is_mozilla fn checks for Mozilla version 0.96 or greater */
f(util_is_mozilla(ua, "0", "96")) {
/* Set the return code to 302 Redirect */
protocol_status(sn, rq, PROTOCOL_REDIRECT, NULL);
/* The error handling fns use this to set Location: */
pblock_nvinsert("url", url, rq->vars);
return REQ_ABORTED;
}
/* No match. Old client. */
/* If there is an alternate document specified, use it. */
if(alt) {
pb_param *pp = pblock_find("ppath", rq->vars);
/* Trash the old value */
FREE(pp->value);
/* Dup it because the library will later free this pblock */
pp->value = STRDUP(alt);
return REQ_PROCEED;
}
/* Else do nothing */
return REQ_NOACTION;
}
See also
shexp_casecmp, shexp_match
shexp_match base/shexp.h
The shexp_match function compares a specified pre-validated shell expression against a specified string. It returns one of three possible values representing match, no match, and invalid comparison. Note that (in contrast with the shexp_casecmp function) the comparison is case-sensitive.
Note that shexp_match doesn't perform validation of the shell expression; instead the function assumes that you have already called shexp_valid.
Use this function if you have a shell expression like *.netscape.com
and you want to make sure that a string matches it, such as foo.netscape.com
.
Syntax
#include <base/shexp.h>
int shexp_match(char *str, char *exp);
Returns
Parameters
char *str is the string to be compared.
char *exp is the pre-validated shell expression (possibly containing wildcard characters) to compare against.
See also
shexp_casecmp, shexp_cmp, shexp_match
shexp_valid base/shexp.h
The shexp_valid function validates a specified shell expression named by exp. Use this function to validate a shell expression before using the function shexp_match to compare the expression with a string.
Syntax
#include <base/shexp.h>
int shexp_valid(char *exp);
Returns
NON_SXP
if exp is a standard string
INVALID_SXP
if exp is a shell expression, but invalid
VALID_SXP
if exp is a valid shell expression
Parameters
char *exp is the pre-validated shell expression (possibly containing wildcard characters) to be used later in a shexp_match comparison.
See also
shexp_casecmp, shexp_match, shexp_cmp
shmem_alloc base/shmem.h
The shmem_alloc function allocates a region of shared memory of the given size, using the given name to avoid conflicts between multiple regions within the program. The region will not be automatically grown if its boundaries are over-run, use the shmem_realloc function for that.
This function must be called before any daemon workers are spawned, in order for the handle to the shared region to be inherited by the children.
Because of the requirement that the region must be inherited by the children, the region cannot be re-allocated with a larger size when necessary.
Syntax
#include <base/shmem.h>
shmem_s *shmem_alloc(char *name, int size, int expose);
Returns
A pointer to a new shared memory region.
Parameters
char *name is the name for the region of shared memory being created. The value of name must be unique to the program that calls the shmem_alloc function or conflicts will occur.
int size is the number of characters of memory to be allocated for the shared memory.
int expose is either zero or non-zero. If non-zero, then on systems that support it, the file that is used to create the shared memory becomes visible to other processes running on the system
See also
shmem_free
shmem_free base/shmem.h
The shmem_free function de-allocates (frees) the specified region of memory.
Syntax
#include <base/shmem.h>
void *shmem_free(shmem_s *region);
Returns
void
Parameters
shmem_s *region is a shared memory region to be released.
See also
shmem_allocate
STRDUP netsite.h
The STRDUP macro is a platform-independent substitute for the common Unix library routine strdup. It creates a new copy of a string.
The strdup routine is functionally equivalent to
char *newstr = (char *) MALLOC(strlen(str) + 1);
strcpy(newstr, str);
Syntax
#include <netsite.h>
STRDUP(ptr);
Returns
A pointer to the new string.
Parameters
ptr is a pointer to a string.
Example
while(fgets(buf, MAX_ACF_LINE, f)) {
/* Blast linefeed that stdio leaves on there */
uf[strlen(buf) - 1] = '0';
hosts = (char **) REALLOC(hosts, (num_hosts + 2) * sizeof(char *));
hosts[num_hosts++] = STRDUP(buf);
hosts[num_hosts] = NULL;
}
See also
MALLOC, FREE, REALLOC
system_errmsg base/file.h
The system_errmsg function returns the last error that occurred from the most recent system call. This function is implemented as a macro that returns an entry from the global array sys_errlist
. Use this macro to help with I/O error diagnostics.
Syntax
#include <base/file.h>
char *system_errmsg(int para1);
Returns
A string containing the text of the latest error message that resulted from a system call.
Parameters
int para1 is reserved, and should always have the value 0.
See also
system_fclose, system_fread, system_fopenRO, system_fwrite
system_fclose base/file.h
The system_fclose function closes a specified file descriptor. Note that system_fclose must be called for every file descriptor opened by any of the system_fopen functions.
Syntax
#include <base/file.h>
int system_fclose(SYS_FILE fd);
Returns
IO_ERROR
if the close failed
Parameters
SYS_FILE fd is the platform-independent file descriptor.
Example
static SYS_FILE logfd = SYS_ERROR_FD;
// this function closes global logfile
void brief_terminate()
{
system_fclose(logfd);
logfd = SYS_ERROR_FD;
}
See also
system_errmsg, system_fread, system_fopenRO, system_fwrite
system_flock base/file.h
The system_flock function locks the specified file against interference from other processes. Use system_flock if you do not want other processes using the file you currently have open. Note that overusing file locking can cause performance degradation and possibly lead to deadlocks.
Syntax
#include <base/file.h>
int system_flock(SYS_FILE fd);
Returns
IO_OK
if the lock succeeded
IO_ERROR
if the lock failed
Parameters
SYS_FILE fd is the platform-independent file descriptor.
See also
system_fclose, system_fread, system_fopenRO, system_fwrite, system_ulock
system_fopenRO base/file.h
The system_fopenRO function opens the file identified by path in read-only mode and returns a valid file descriptor. Use this function to open files that will not be modified by your program. In addition, you can use system_fopenRO to open a new file buffer structure using filebuf_open.
Syntax
#include <base/file.h>
SYS_FILE system_fopenRO(char *path);
Returns
Parameters
char *path is the file name.
See also
system_fclose, system_fread, system_fopenRW, system_fopenWA, system_fwrite, system_ulock
system_fopenRW base/file.h
The system_fopenRW function opens the file identified by path in read-write mode and returns a valid file descriptor. Note that if the file already exists, system_fopenRW does not truncate it. Use this function to open files that will be read from and written to by your program.
Syntax
#include <base/file.h>
SYS_FILE system_fopenRW(char *path);
Returns
Parameters
char *path is the file name.
Example
/* If any errors, just skip it. */
if(stat(pathname, &finfo) == -1)
break;
fd = system_fopenRO(pathname);
if(fd == SYS_ERROR_FD)
break;
See also
system_fclose, system_fread, system_fopenRO, system_fopenWA, system_fwrite, system_ulock
system_fopenWA base/file.h
The system_fopenWA function opens the file identified by path in append mode and returns a valid file descriptor. Use this function to open those files that your program will append data to.
Syntax
#include <base/file.h>
SYS_FILE system_fopenWA(char *path);
Returns
Parameters
char *path is the file name.
See also
system_fclose, system_fread, system_fopenRO, system_fopenRW, system_fwrite, system_ulock
system_fread base/file.h
The system_fread function reads a specified number of bytes from a specified file into a specified buffer. It returns the number of bytes read. Note that before system_fread can be used, you must open the file using any of the system_fopen functions, except system_fopenWA.
Syntax
#include <base/file.h>
int system_fread(SYS_FILE fd, char *buf, int sz);
Returns
The number of bytes read, which may be less than the requested size if an error occurred or the end of the file was reached before that number of characters 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.
See also
system_fclose, system_fopenRO, system_fopenRW, system_fopenWA, system_fwrite, system_ulock
system_fwrite base/file.h
The system_fwrite function writes a specified number of bytes from a specified buffer into a specified file.
Note that before system_fwrite can be used, you must open the file using any of the system_fopen functions, except system_fopenRO.
Syntax
#include <base/file.h>
int system_fwrite(SYS_FILE fd, char *buf, int sz);
Returns
IO_OK
if the write succeeded
IO_ERROR
if the write failed
Parameters
SYS_FILE fd is the platform-independent file descriptor.
char *buf is the buffer containing the bytes to be written.
int sz is the number of bytes to write to the file.
See also
system_fclose, system_fopenRO, system_fopenRW, system_fopenWA, system_fwrite_atomic, system_ulock
system_fwrite_atomic base/file.h
The system_fwrite_atomic function writes a specified number of bytes from a specified buffer into a specified file. The function also locks the file prior to performing the write, and then unlocks it when done, thereby avoiding interference between simultaneous write actions. Note that before system_fwrite_atomic can be used, you must open the file using any of the system_fopen functions.
Syntax
#include <base/file.h>
int system_fwrite_atomic(SYS_FILE fd, char *buf, int sz);
Returns
IO_OK
if the write/lock succeeded
IO_ERROR
if the write/lock failed
Parameters
SYS_FILE fd is the platform-independent file descriptor.
char *buf is the buffer containing the bytes to be written.
int sz is the number of bytes to write to the file.
Example
logmsg = (char *)
MALLOC(strlen(ip) + 1 + strlen(method) + 1 + strlen(uri) + 1 + 1);
len = util_sprintf(logmsg, "%s %s %sn", ip, method, uri);
/* The atomic version uses locking to prevent interference */
system_fwrite_atomic(logfd, logmsg, len);
FREE(logmsg);
See also
system_fclose, system_fopenRO, system_fopenRW, system_fopenWA, system_fwrite, system_ulock
system_gmtime base/file.h
The system_gmtime function is a thread-safe version of the standard gmtime function.
Syntax
#include <base/file.h>
struct tm *system_gmtime(const time_t *tp, const struct tm *res);
Returns
a pointer to a calendar time (tm) structure containing the GMT time. Note that, depending on your system, it may point to the data item represented by the second parameter, or it may point to a statically-allocated item. For portability, do not assume either situation.
Parameters
time_t *tp is an arithmetic time.
tm *res is a pointer to a calendar time (tm) structure.
Example
time_t tp;
struct tm res, *resp;
...
tp = time(NULL);
resp = system_gmtime(&tp, &res);
See also
system_localime
system_localtime base/file.h
The system_localtime function is a thread-safe version of the standard localtime function.
Note that this is implemented as a macro.
Syntax
#include <base/file.h>
struct tm *system_localtime(const time_t *tp, const struct tm *res);
Returns
a pointer to a calendar time (tm) structure containing the local time. Note that, depending on your system, it may point to the data item represented by the second parameter, or it may point to a statically-allocated item. For portability, do not assume either situation.
Parameters
time_t *tp is an arithmetic time.
tm *res is a pointer to a calendar time (tm) structure.
Example
time_t tp;
struct tm res, *resp;
...
tp = time(NULL);
resp = system_localtime(&tp, &res);
See also
system_gmtime
system_ulock base/file.h
The system_ulock function unlocks the specified file that has been locked by the function system_lock. For more information about locking, see system_flock.
Syntax
#include <base/file.h>
int system_ulock(SYS_FILE fd);
Returns
IO_OK
if the unlock succeeded
IO_ERROR
if the unlock failed
Parameters
SYS_FILE fd is the platform-independent file descriptor.
See also
system_fclose, system_flock, system_fopenRO, system_fopenRW, system_fopenWA, system_fwrite
system_unix2local base/file.h
The system_unix2local function converts a specified Unix-style pathname to a local pathname named by lp. Use this function when you have a file name in the Unix format (such as one containing forward slashes), and you are running Windows NT. You can use system_unix2local to convert the Unix file name into the format that Windows NT accepts. In the Unix environment, this function does nothing.
Syntax
#include <base/file.h>
char *system_unix2local(char *path, char *lp);
Returns
A pointer to the local path string
Parameters
char *path is the Unix-style pathname to be converted.
char *lp is the local pathname.
See also
system_fclose, system_flock, system_fopenRO, system_fopenRW, system_fopenWA, system_fwritesysthread_current base/systhr.h
">
systhread_current base/systhr.h
The systhread_current function returns a pointer to the current thread.
Syntax
#include <base/systhr.h>
SYS_THREAD systhread_current(void);
Returns
A pointer to the current thread
Parameters
void
See also
systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep,systhread_start, systhread_terminate, systhread_timerset
systhread_getdata base/systhr.h
The systhread_getdata function gets data that is associated with a specified key in the current thread
Syntax
#include <base/systhr.h>
void *systhread_getdata(int key);
Returns
Parameters
int key is the value associated with the stored data by a systhread_setdata function. Keys are assigned by the systhread_newkey function.
See also
systhread_current, systhread_newkey, systhread_setdata, systhread_sleep,systhread_start, systhread_terminate, systhread_timerset
systhread_newkey base/systhr.h
The systhread_newkey function allocates a new integer key (identifier) for thread-private data. Use this key to identify a variable that you want to localize to the current thread; then use the systhread_setdata function to associate a value with the key.
Syntax
#include <base/systhr.h>
int systhread_newkey(void);
Returns
An integer key.
Parameters
void
See also
systhread_current, systhread_getdata, systhread_setdata, systhread_sleep, systhread_start, systhread_terminate, systhread_timerset
systhread_setdata base/systhr.h
The systhread_setdata function associates data with a specified key number for the current thread. Keys are assigned by the systhread_newkey function.
Syntax
#include <base/systhr.h>
void systhread_start(int key, void *data);
Returns
void
Parameters
int key is the priority of the thread.
void *data is the pointer to the string of data to be associated with the value of key.
See also
systhread_current, systhread_getdata, systhread_newkey, systhread_sleep, systhread_start, systhread_terminate, systhread_timerset
systhread_sleep base/systhr.h
The systhread_sleep function puts the calling thread to sleep for a given time.
Syntax
#include <base/systhr.h>
void systhread_sleep(int milliseconds);
Returns
void
Parameters
int milliseconds is the number of milliseconds the thread is to sleep.
See also
systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_start, systhread_terminate, systhread_timerset
systhread_start base/systhr.h
The systhread_start function creates a thread with the given priority, allocates a stack of a specified number of bytes, and calls a specified function with a specified argument.
Syntax
#include <base/systhr.h>
SYS_THREAD systhread_start(int prio, int stksz, void (*fn)(void *),
void *arg);
Returns
Parameters
int prio is the priority of the thread. Priorities are system-dependent.
int stksz is the stack size in bytes. If stksz is zero, the function allocates a default size.
void (*fn)(void *) is the function to call.
void *arg is the argument for the fn function.
See also
systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep, systhread_terminate, systhread_timerset
systhread_terminate base/systhr.h
The systhread_terminate function terminates a specified thread.
Syntax
#include <base/systhr.h>
void systhread_terminate(SYS_THREAD thr);
Returns
void
Parameters
thr is the thread to terminate.
See also
systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep, systhread_start, systhread_timerset
systhread_timerset base/systhr.h
The systhread_timerset function starts or resets the interrupt timer interval for a thread system.
NOTE
Because most systems don't allow the timer interval to be changed, this should be considered a suggestion, rather than a command.
Syntax
#include <base/systhr.h>
void systhread_timerset(int usec);
Returns
void
Parameters
int usec is the time, in microseconds
See also
systhread_current, systhread_getdata, systhread_newkey, systhread_setdata, systhread_sleep,systhread_start, systhread_terminate
util_can_exec base/util.h
The util_can_exec function checks that a specified file can be executed, returning either a 1 (executable) or a 0. The function checks to see if the file can be executed by the user with the given user and group ID.
Note that util_can_exec is only available under Unix.
Use this function before executing a program using the exec system call.
Syntax
#include <base/util.h>
int util_can_exec(struct stat *finfo, uid_t uid, gid_t gid);
Returns
Parameters
stat *finfo is the stat structure associated with a file.
uid_t uid is the Unix user id.
gid_t gid is the Unix group id. Together with uid, this determines the permissions of the Unix user.
See also
util_env_create, util_getline, util_hostname
util_chdir2path base/util.h
The util_chdir2path function changes the current directory to a specified directory, which should point to a file.
When running under Windows NT, use a semaphore to ensure that more than one thread does not call this function at the same time.
Use util_chdir2path when you want to make file access a little quicker, because you do not need to use a full path with this function.
Syntax
#include <base/util.h>
int util_chdir2path(char *path);
Returns
Parameters
char *path is the name of a directory.
See also
util_env_create, util_getline, util_hostname
util_env_create base/util.h
The util_env_create function creates and allocates the environment specified by env, returning a pointer to the environment. If the parameter env is NULL, the function allocates a new environment. Use util_env_create to create an environment when executing a new program.
Syntax
#include <base/util.h>
char **util_env_create(char **env, int n, int *pos);
Returns
A pointer to an environment.
Parameters
char **env is the existing environment or NULL.
int n is the maximum number of environment entries that you want in the environment.
int *pos is the an integer that keeps track of the number of entries used in the environment.
See also
util_env_replace, util_env_str, util_env_free, util_env_find
util_env_find base/util.h
The util_env_find function locates the string denoted by a name in a specified enviroment and returns the associated value. Use this function to find an entry in an environment.
Syntax
#include <base/util.h>
char *util_env_find(char **env, char *name);
Returns
Parameters
char **env is the environment.
char *name is the name of a name-value pair.
See also
util_env_replace, util_env_str, util_env_free, util_env_create
util_env_free base/util.h
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
#include <base/util.h>
void util_env_free(char **env);
Returns
void
Parameters
char **env is the environment to be freed.
See also
util_env_replace, util_env_str, util_env_find, util_env_create
util_env_replace base/util.h
The util_env_replace function replaces the occurrence of the variable denoted by a name in a specified environment with a specified value. Use this function to change the value of a setting in an environment.
Syntax
#include <base/util.h>
void util_env_replace(char **env, char *name, char *value);
Returns
void
Parameters
char **env is the environment.
char *name is the name of a name-value pair.
char *value is the new value to be stored.
See also
util_env_str, util_env_free, util_env_find, util_env_create
util_env_str base/util.h
The util_env_str function creates an environment entry and returns it. Note that this function does not check for nonalphanumeric symbols in the name (such as the equal sign "="
). You can use this function to create a new environment entry.
Syntax
#include <base/util.h>
char *util_env_str(char *name, char *value);
Returns
A newly-allocated string containing the name-value pair
Parameters
char *name is the name of a name-value pair.
char *value is the new value to be stored.
See also
util_env_replace, util_env_free, util_env_find, util_env_create
util_getline base/util.h
The util_getline function scans the specified buffer to find an LF- or CRLF-terminated string. The function stores the string in another specified buffer, and NULL-terminates it. Finally, the function returns a value that signals whether the operation stored anything in the buffer or encountered an error, and whether it reached the end of the file.
Use this function to scan lines out of a text file, such as a configuration file.
Syntax
#include <base/util.h>
int util_getline(filebuf *buf, int lineno, int maxlen, char *l);
Returns
Parameters
filebuf *buf is the buffer to be scanned.
int lineno is used for error diagnostics to include the line number in the error message. The caller is responsible for making sure the line number is accurate.
int maxlen is the maximum number of characters that can be written into l.
char *l is the buffer into which to store the string. Note that the user is responsible for allocating and deallocating l.
See also
util_can_exec, util_env_create, util_hostname
util_hostname base/util.h
The util_hostname function retrieves the local host name and returns it as a string. If the function cannot find a fully-qualified domain name, it returns NULL. Note that you can reallocate or free this string. Use this function to determine the name of the system you are on.
Syntax
#include <base/util.h>}
char *util_hostname(void);
Returns
Parameters
No parameter is required.
See also
util_can_exec, util_env_create, util_getline
util_is_mozilla base/util.h
The is_mozilla function checks whether a specified user-agent is a Netscape browser of at least a specified revision level, returning a 1 if it is and 0 otherwise. It uses strings to specify the revision level to avoid ambiguities like 1.56 > 1.5.
Syntax
#include <base/util.h>
int util_is_mozilla(char *ua, char *major, char *minor);
Returns
Parameters
char *ua is the user-agent
char *major is the major release number (to the left of the decimal point).
char *minor is the minor release number (to the right of the decimal point).
Example
see the example under shexp_cmp
See also
util_is_url, util_later_than
util_is_url base/util.h
The util_is_url function checks whether a string is a URL, returning 1 if it is and 0 otherwise.
Syntax
#include <base/util.h>
int util_is_url(char *url);
Returns
Parameters
char *url is the string to be examined.
See also
util_is_mozilla, util_later_than
util_itoa base/util.h
The util_itoa function converts a specified integer to a string, and returns the length of the string. Use this function to create a textual representation of a number.
Syntax
#include <base/util.h>
int util_itoa(int i, char *a);
Returns
The length of the string created in a
Parameters
int i is the integer to be converted.
char *a is the ASCII string that represents the value. Note that the user is responsible for the allocation and deallocation of a, and it should be at least 32 bytes long.
See also
util_sh_escape
util_later_than base/util.h
The util_later_than function compares the date specified in a time structure against a date specified in a string. If the date in the string is later than or equal to the one in the time structure, the function returns 1. Use this function to handle RFC 822, 850, and ctime formats.
Syntax
#include <base/util.h>
int util_later_than(struct tm *lms, char *ims);
Returns
Parameters
tm *lms is the time structure containing a date.
char *ims is the string containing a date.
See also
util_is_mozilla, util_is_url, util_itoa
util_sh_escape base/util.h
The util_sh_escape function parses a specified string and places a backslash (\
) in front of any shell-special characters, returning the resultant string. Use this function to ensure that strings from clients won't cause a shell to do anything unexpected.
Syntax
#include <base/util.h>
char *util_sh_escape(char *);
Returns
A newly allocated string
Parameters
char *s is the string to be parsed.
See also
util_uri_escape
util_snprintf base/util.h
The util_snprintf function formats a specified string, using a specified format, into a specified buffer using the printf-style syntax and performs bounds checking. It returns the number of characters in the formatted buffer.
For more information, see the documentation on the printf function for the run-time library of your compiler.
Syntax
#include <base/util.h>
int util_snprintf(char *s, int n, char *fmt, ...);
Returns
The number of characters formatted into the buffer.
Parameters
char *s is the buffer to receive the formatted string.
int n is the maximum number of bytes allowed to be copied.
char *fmt is the format string. Note that the function handles only %d
and %s
strings; it does not handle any width or precision strings.
... represents a sequence of parameters for the printf function.
Example
Similar to the example for util_sprintf.
See also
util_sprintf, util_vsnprintf, util_vsprintf
util_sprintf base/util.h
The util_sprintf function formats a specified string, using a specified format, into a specified buffer using the printf-style syntax without bounds checking. It returns the number of characters in the formatted buffer.
Because util_sprintf doesn't perform bounds checking, use this function only if you are certain that the string fits the buffer. Otherwise, use the function util_snprintf. For more information, see the documentation on the printf function for the run-time library of your compiler.
Syntax
#include <base/util.h>
int util_sprintf(char *s, char *fmt, ...);
Returns
The number of characters printed.
Parameters
char *s is the buffer to receive the formatted string.
char *fmt is the format string. Note that the function handles only %d
and %s
strings; it does not handle any width or precision strings.
... represents a sequence of parameters for the printf function.
Example
int brief_log(pblock *pb, Session *sn, Request *rq)
{
char *method = pblock_findval("method", rq->reqpb);
char *uri = pblock_findval("uri", rq->reqpb);
char *ip = pblock_findval("ip", sn->client);
/* Temp vars */
char *logmsg;
int len;
logmsg = (char *)
MALLOC(strlen(ip) + 1 + strlen(method) + 1
+ strlen(uri) + 1 + 1);
len = util_sprintf(logmsg, "%s %s %sn", ip, method, uri);
/* The atomic version uses locking to prevent interference */
system_fwrite_atomic(logfd, logmsg, len);
FREE(logmsg);
return REQ_PROCEED;
}
See also
util_snprintf, util_vsnprintf, util_vsprintf
util_strcasecmp base/systems.h
The util_strcasecmp function performs a comparison of two alpha-numeric strings and returns a -1, 0, or 1 to signal which is larger or that they are identical.
Note that the function's comparison is not case-sensitive.
Syntax
#include <base/systems.h>
int util_strcasecmp(const char *s1, const char *s2);
Returns
Parameters
char *s1 is the first string.
char *s2 is the second string.
See also
util_strncasecmp
util_strncasecmp base/systems.h
The util_strncasecmp function performs a comparison of the first n characters in the alpha-numeric strings and returns a -1, 0, or 1 to signal which is larger or that they are identical.
Note that the function's comparison is not case-sensitive.
Syntax
#include <base/systems.h>
int util_strncasecmp(const char *s1, const char *s2, int n);
Returns
Parameters
char *s1 is the first string.
char *s2 is the second string.
int n is the number of initial characters to compare.
See also
util_strcasecmp
util_uri_escape base/util.h
The util_uri_escape function converts any special characters in a specified string into the URI format, and returns the escaped string. Use util_uri_escape before sending the URI back to the client.
Syntax
#include <base/util.h>
char *util_uri_escape(char *d, char *s);
Returns
The string (possibly newly allocated) with escaped characters replaced.
Parameters
char *d is a string. If d is not NULL, the function copies the formatted string into d and returns it. If d is NULL, the function allocates a properly-sized string and copies the formatted special characters into the new string, then returns it.
See also
util_uri_is_evil, util_uri_parse, util_uri_unescape
util_uri_is_evil base/util.h
The util_uri_is_evil function checks a specified URI and returns 1 if it contains ../ or //. Use this function to make sure that a URI given by a client won't do anything unexpected.
Syntax
#include <base/util.h>
int util_uri_is_evil(char *t);
Returns
Parameters
char *t is the URI to be checked.
See also
util_uri_escape, util_uri_parse
util_uri_parse base/util.h
The util_uri_parse function removes /../, /./, and // in a specified URI. You can use this function to convert a URI's bad sequences into valid ones. First use the function util_uri_is_evil to determine whether the function has a bad sequence.
Syntax
#include <base/util.h>
void util_uri_parse(char *uri);
Returns
void
Parameters
char *uri is the URI to be converted.
See also
util_uri_is_evil, util_uri_unescape
util_uri_unescape base/util.h
The util_uri_unescape function converts the encoded characters of a specified URI into special characters in place.
Syntax
#include <base/util.h>
void util_uri_unescape(char *uri);
Returns
void
Parameters
char *uri is the URI to be converted.
See also
util_uri_escape, util_uri_is_evil, util_uri_parse
util_vsnprintf base/util.h
The util_vsnprintf function formats a specified string, using a specified format, into a specified buffer using the vprintf-style syntax and performs bounds checking. It returns the number of characters in the formatted buffer.
For more information, see the documentation on the printf function for the run-time library of your compiler.
Use this function if you want a vsprintf syntax that takes a standard argument format. For more information, see the documentation on the vsprintf function for the run-time library of your compiler.
Syntax
#include <base/util.h>
int util_vsnprintf(char *s, int n, register char *fmt, va_list args);
Returns
The number of characters printed
Parameters
char *s is the buffer to receive the formatted string.
int n is the maximum number of bytes allowed to be copied.
register char *fmt is the format string. Note that 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.
See also
util_sprintf, util_vsprintf
util_vsprintf base/util.h
The util_vsprintf function formats a specified string, using a specified format, into a specified buffer using the vprintf-style syntax without bounds checking. It returns the number of characters in the formatted buffer.
For more information, see the documentation on the printf function for the run-time library of your compiler.
Use this function if you want a vsprintf syntax that takes a standard argument format. For more information, see the documentation on the vsprintf function for the run-time library of your compiler.
Syntax
#include <base/util.h>
int util_vsprintf(char *s, register char *fmt, va_list args);
Returns
The number of characters printed
Parameters
char *s is the buffer to receive the formatted string.
register char *fmt is the format string. Note that 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.
See also
util_snprintf, util_vsnprintf