C API Function Categories

The C API functions fall into these categories, which are described in the sections that follow:

Memory Allocation Functions	A set of wrapper functions for the malloc family of memory allocation functions that attempt to recover automatically from a low-memory situation.
Data Structures and Related Functions	Data structures and related functions for manipulating data common in HTTP connection requests and working with active HTTP connections.
Core Functions	An extensive set of functions for interacting with AOLserver.
Database Functions	A set of functions for accessing the database and obtaining information about the database.

Memory Allocation Functions

The AOLserver uses dynamically allocated memory extensively. To ease the burden of checking for memory-allocation failures, the AOLserver provides wrapper functions for the malloc family of memory allocation functions.

The AOLserver functions differ from their system counterparts: instead of returning NULL on memory-allocation failure, they instead attempt to recover automatically from a low-memory situation. The AOLserver attempts to recover by first freeing any memory from internal caches that can safely be flushed. If flushing caches fails to free enough memory, the AOLserver will wait 1 second and then, if necessary, another 10 seconds, in the hope that the memory shortage is temporary, perhaps caused by another program that will shortly stop executing. If the AOLserver cannot recover from a low-memory situation, it logs the failure and shuts down the server.

Using the AOLserver memory allocation functions is a matter replacing the corresponding malloc family system function with a function of the same name preceded by ns_. You can currently mix calls to the ns_ functions and their system counterparts. However, this is not recommended because the interface may change in future releases of AOLserver.

The memory allocation functions are listed below.

Function	Description
Ns_Calloc	Allocate a zero-filled block of memory
Ns_Free	Free a block of allocated memory
Ns_Malloc	Allocate a block of memory
Ns_Realloc	Resize a previously allocated block of memory
Ns_StrCopy	Copy a string or NULL value using Ns_Malloc
Ns_StrDup	Copy a string using Ns_Malloc

Data Structures and Related Functions

The AOLserver C API provides the following data structures for manipulating data common in HTTP connection requests and working with active HTTP connections.

Ns_Set Structure	A string key-value pair structure, such as for database rows, HTTP header information, and HTTP form data.
Ns_DString Structure	A structure used to implement dynamic memory blocks, typically strings.
Ns_Conn Structure	A structure that includes all state information of an active HTTP connection.
Ns_Request Structure	A structure that contains the various parts of the HTTP request of an active connection.

Ns_Set Structure

An AOLserver C API function must often access data as sets of key-value pairs, for example:

• a row of data from the database

• HTTP header information

• HTML form data

The Ns_Set structure provides a convenient mechanism for manipulating key-value pairs of string data. The key-value pairs in an Ns_Set are Ns_SetFields (called "fields" for short). The Ns_SetField structure has the following definition:

    
    typedef struct {
    	char *name;		  /* Key name of field. */
    	char *value;		 /* Value of field (can be NULL) */
    } Ns_SetField;
    

The Ns_Set structure has the following definition:

    
    typedef struct {
    	char 	*name;    	/* Name of set (can be NULL) */
    	int   size;    		/* Current number of fields */
    	int   maxSize;			 /* (used internally) */
    	Ns_SetField *fields; 	/* Array of Ns_SetField's */
    } Ns_Set;
    

Within the Ns_Set, the fields are stored as an array, in the order in which the fields were added to the set. The array of fields grows dynamically as fields are entered.

To access the fields of a set, either use the lookup functions described below or loop through the fields directly as in the following code fragment:

    
    	for (n = 0; n < Ns_SetSize(set); ++n) {
    		printf("field %d name: %s value: %s\n",
    			n, Ns_SetKey(set, n), Ns_SetValue(set, n));
    	}

The functions that use the Ns_Set data structure are listed in the following table.

Function	Description
Ns_SetCopy	Create a new copy of a set
Ns_SetCreate	Create a new Ns_Set
Ns_SetDelete	Remove a field from a set by field index
Ns_SetDeleteKey	Remove a field from a set by key name
Ns_SetFind	Locate the index of a field within an Ns_Set
Ns_SetFree	Free memory used by an Ns_Set
Ns_SetGet	Return the value for a field
Ns_SetIDeleteKey	Remove a field from a set by key name case-insentively
Ns_SetIFind	Locate the index of a field case-insensitively
Ns_SetIGet	Return the value for a field case-insensitively
Ns_SetIUnique	Check if a key in an Ns_Set is unique (case insensitive)
Ns_SetKey	Return the key name of a field
Ns_SetLast	Return the index of the last element of a set
Ns_SetListFind	Locate a set by name in a set list
Ns_SetListFree	Free a list of sets
Ns_SetMerge	Merge two sets
Ns_SetMove	Move fields from one set to the end of another
Ns_SetName	Return the name of a set
Ns_SetPrint	Print the contents of a set to the AOLserver error log
Ns_SetPut	Add a field to an Ns_Set
Ns_SetPutValue	Set the value of a field
Ns_SetSize	Return the current size of a set
Ns_SetSplit	Split a set into an array of new sets
Ns_SetTrunc	Truncate an Ns_Set
Ns_SetUnique	Check if a key in an Ns_Set is unique (case sensitive)
Ns_SetUpdate	Update an Ns_Set value
Ns_SetValue	Return the value of a field
Ns_TclEnterSet	Make an Ns_Set accessible through Tcl
Ns_TclFreeSet	Free an Ns_Set
Ns_TclGetSet	Return the Ns_Set for the specified set ID
Ns_TclGetSet2	Return the Ns_Set for the specified set ID in a pointer

Ns_DString Structure

An AOLserver C API function often uses dynamically allocated strings. The Ns_DString structure is used for this purpose. (The AOLserver Ns_DString is based on the Tcl_DString found in the Tcl C API.) Ns_DStrings contains a small amount of static space but will overflow to allocated memory if needed. Within the AOLserver, pointers to Ns_DStrings are often used where other APIs would require a pointer to a buffer and a specific size.

The Ns_DString structure has the following definition:

    typedef struct {
      char *string;    /* Points to either static space or dynamically
                          allocated memory */
      int length;      /* Number of bytes in string */
      int spaceAvl;    /* Number of bytes unused but allocated for
                          string */
      char staticspace [NS_DSTRING_STATIC_SIZE]; 
                       /* Initial static space. */
    } Ns_DString;

NS_DSTRING_STATIC_SIZE is by default set to 512 bytes.

The functions that use the Ns_DString data structure are listed in the following table.

Ns_DStringAppend	Append a string to an Ns_DString
Ns_DStringAppendArg	Append argument to an Ns_DString
Ns_DStringExport	Export the string of an Ns_DString
Ns_DStringFree	Free any allocated memory used by an Ns_DString
Ns_DStringInit	Initialize an Ns_DString
Ns_DStringLength	Return the current length of an Ns_DString
Ns_DStringNAppend	Append n-characters of a string to an Ns_DString
Ns_DStringPrintf	Append a formatted string to an Ns_DString
Ns_DStringTrunc	Truncate an Ns_DString
Ns_DStringValue	Return the current value of an Ns_DString
Ns_DStringVarAppend	Append a variable number of strings to an Ns_DString

Ns_Conn Structure

All functions that handle connection requests, which we refer to as AOLserver operations, take as an argument a pointer to an Ns_Conn structure. This structure contains all information and state about the active connection. The public members that you may find useful include:

    typedef struct Ns_Conn {
    Ns_Request *request;

Pointer to an Ns_Request structure that holds information about the HTTP request associated with the connection. The Ns_Request structure is described below.

    Ns_Set *headers;

Pointer to an Ns_Set whose fields are the HTTP request headers sent by the HTTP client.

    Ns_Set *outputheaders;

Pointer to an Ns_Set whose fields are the headers to be sent to the client.

    char *authUser;

Decoded user name from the header information. Because the AOLserver does not authenticate the user when world permission is allowed to a URL, this user may not be a valid AOLserver user.

    char *authPasswd;

Decoded user password from the header information. Because the AOLserver does not authenticate the user when world permission is allowed to a URL, this password may not be the user's actual password.

    int contentLength;

Number of bytes in the content sent by the HTTP client.

    } Ns_Conn;

Ns_Request Structure

The Ns_Request structure breaks a complete HTTP request line into its many parts.

    typedef struct Ns_Request {
    char *line;

A copy of the actual request line sent by the HTTP client.

    char *method;

HTTP method; for example GET or POST.

    char *protocol;

Protocol of the HTTP request, e.g., http or ftp. Normally, this element is NULL because the AOLserver does not currently proxy requests, so fully-qualified URLs in HTTP requests are rejected.

    char *host;

Host part of the URL in the HTTP request. Normally this element is NULL because the AOLserver does not currently proxy HTTP requests.

    unsigned short port;

Port explicitly specified in the URL of the HTTP request. This element is 0 when no port is explicitly specified.

    char *url;

URL after having been normalized with Ns_NormalizePath() function and after removing any query data that may have been appended.

    char *query;

Any query data appended to the URL. (Query data are any data that follow a question mark at the end of a URL. They can be used to pass arguments to an operation.)

    int urlc;

Number of path elements in the normalized URL. This is similar to the argc parameter to the main() function in a C program. For example, if the URL were /some/url, urlc would be 2.

    char **urlv;

NULL-terminated array of pointers to strings for each path element of the normalized URL. This is similar to the argv parameter to the main() function in a C program. For example, if the URL was /some/url, urlv[0] would be "some", urlv[1] would be "url", and urlv[2] would be NULL.

    double version;

Version of the HTTP request, usually 0.9 or 1.0.

    } Ns_Request;

The AOLserver provides several convenient functions for working with the elements of the Ns_Request structure. The functions that use the Ns_Request data structure are listed in the following table.

Ns_FreeRequest	Free memory used by an Ns_Request
Ns_ParseRequest	Parse an HTTP request line into an Ns_Request
Ns_SetRequestUrl	Fill in request structure
Ns_SkipUrl	Skip past path elements in the URL of a request

Core Functions

The groups of core functions listed below are described in the following subsections.

Registration Functions	Functions used to register other functions to handle HTTP requests or implement traces, chores, or shutdown procedures.
Access Control Functions	Functions used to check authorization on a method/URL combination or implement an alternative authorization procedure.
Caching Functions	Functions used to manage caching.
Configuration File Functions	Functions used to access the in-memory representation of the configuration file data.
URL and File Functions	Functions used to convert URLs to files within the pages directory and test the files for various properties
HTTP Header-Related Functions	Functions used to generate and send HTTP headers to a browser
HTTP Complete Response Functions	Functions used to generate complete responses to HTTP requests
HTTP Simple Response Functions	Functions used to call Ns_ConnReturnStatus or Ns_ConnReturnNotice with the appropriate status code, reason, and notice message when the only response required by the AOLserver is the HTTP status line.
HTTP Low-Level Connection Functions	Functions used to send data directly to the client without formatting or immediate buffering of the data.
Logging Functions	Functions used to write information to the AOLserver log file.
Memory Pool Functions	Functions used to manipulate the memory pools used by AOLserver.
Mime-Related Functions	Functions used to access and manipulate Mime type information.
Module Logging Realms Functions	Functions used to control realms for module logging.
Scheduled Procedures Functions	Functions used to schedule procedures to be run daily, weekly, or at specified intervals.
Sockets Interface Functions	Functions for managing sockets.
Socket Driver Interface Functions	Functions for socket drivers.
Storage and Retrieval Functions	Functions used to store and retrieve information specific to URLs or servers.
Synchronization Functions	Functions used to manage condition variables, semaphores, mutexes, events, critical sections, and read/write locks.
Thread Interface Functions	Functions used to interact with the threads interface of AOLserver.
Tcl Interpreter Functions	Functions used to allocate and return Tcl interpreters.
Miscellaneous Functions	Functions used to perform miscellaneous tasks and get information about the server.

Registration Functions

At startup time, the server loads your C module and runs your initialization function. Your initialization function can connect to any external data sources or initialize any data structures it requires. The initialization function then typically calls one or more of the following functions to register other functions within the module as capable of handling URL requests or implementing traces, chores, or shutdown procedures.

The functions in this category are listed in the following table.

Ns_AdpRegisterParser	Register a parser for ADPs
Ns_GetRequest	Return the parameters of a request
Ns_RegisterAtExit	Register an exit procedure.
Ns_RegisterAtPreStartup	Register a procedure for pre-server startup
Ns_RegisterAtSignal	Register a procedure at HUP signal
Ns_RegisterAtStartup	Register a procedure for server startup
Ns_RegisterCleanup	Register a procedure for connection cleanup trace
Ns_RegisterFilter	Register a filter function to handle a method/URL combination
Ns_RegisterProxyRequest	Register a function to proxy requests for a method/protocol combination
Ns_RegisterRequest	Register a function to handle HTTP requests for a method/URL combination
Ns_RegisterReturn	Register a return status for a URL
Ns_RegisterServerShutdown	Register a shutdown procedure for a server.
Ns_RegisterServerTrace	Register a trace procedure for a server.
Ns_RegisterShutdown	Register a shutdown procedure.
Ns_UnRegisterProxyRequest	Unregister a proxy request function
Ns_UnRegisterRequest	Unregister a function

Access Control Functions

The hierarchical access checking authorization system is accessed through the following functions.

Ns_AuthorizeRequest	Check access of a method and URL
Ns_AuthorizeUser	Check username and password
Ns_PermPasswordCheck	Check user's encrypted password
Ns_SetRequestAuthorizeProc	Set function used by Ns_AuthorizeRequest
Ns_SetUserAuthorizeProc	Set function used by Ns_AuthorizeUser

Caching Functions

Caching is managed with the following functions:

Ns_CacheBroadcast	Broadcast to condition variable
Ns_CacheCreate	Create a new cache
Ns_CacheCreateEntry	Create a cache entry
Ns_CacheCreateSz	Create a size-based cache
Ns_CacheDeleteEntry	Delete a cache entry
Ns_CacheFind	Find a cache
Ns_CacheFindEntry	Find a cache entry
Ns_CacheFirstEntry	Get first cache entry
Ns_CacheFlush	Flush all cache entries
Ns_CacheFlushEntry	Delete a cache entry
Ns_CacheFree	Free allocated memory
Ns_CacheGetValue	Get value of cache entry
Ns_CacheKey	Get key of cache entry
Ns_CacheLock	Lock a cache
Ns_CacheMalloc	Allocate memory
Ns_CacheName	Get name of cache
Ns_CacheNextEntry	Get next cache entry
Ns_CacheSetValue	Set value of cache entry
Ns_CacheSetValueSz	Set value of cache entry and adjust cache size
Ns_CacheSignal	Signal cache's condition variable
Ns_CacheTimedGetValue	Wait for cache entry to be set
Ns_CacheTimedWait	Wait for condition variable to be set
Ns_CacheUnlock	Unlock cache
Ns_CacheUnsetValue	Reset cache entry to null
Ns_CacheWait	Wait indefinitely for condition variable to be set

Configuration File Functions

When the server is started, it reads the AOLserver configuration file into memory. You can use the following functions to access the in-memory representation of those data. See Chapter 4 in the AOLserver Administrator's Guide for more information on the AOLserver configuration file.

Ns_ConfigGetBool	Get a boolean configuration file variable
Ns_ConfigGetInt	Get a configuration file integer variable
Ns_ConfigGetInt64	Get a configuration file 64-bit integer variable
Ns_ConfigGetPath	Return configuration file section name
Ns_ConfigGetSection	Get the Ns_Set for a configuration file section
Ns_ConfigGetSections	Return Ns_Sets with configuration file data
Ns_ConfigGetValue	Get a configuration file variable
Ns_ConfigGetValueExact	Get configuration variable case-sensitively

URL and File Functions

AOLserver operations often work with files within the pages directory. These files normally are related to URLs that are requested by clients. The AOLserver provides the following functions for converting URLs to files within the pages directory and testing the files for various properties.

Ns_AbsoluteUrl	Construct a URL from a URL and location
Ns_DecodeUrl	Decode URL query data
Ns_EncodeUrl	Encode URL query data
Ns_HomePath	Construct a path name relative to the AOLserver home directory
Ns_MakePath	Construct a path name from a list of path elements
Ns_ModulePath	Construct a path from base path
Ns_NormalizePath	Normalize a path name
Ns_PathIsAbsolute	Check for an absolute path name
Ns_QueryToSet	Parse query data into Ns_Set
Ns_RelativeUrl	Get relative filename portion of URL
Ns_SetUrlToFileProc	Customize relative file mapping
Ns_UrlIsDir	Check if a directory that corresponds to a URL exists
Ns_UrlIsFile	Check if a file that corresponds to a URL exists
Ns_UrlToFile	Construct the filename that corresponds to a URL

HTTP Header-Related Functions

The C API includes the following functions to generate and send HTTP headers to a browser. If the original request was not HTTP version 1.0 or higher, these functions do not send the headers to the client. This allows you to write header generating code without regard to HTTP version.

Ns_ConnCondSetHeaders	Set the value for a header field conditionally
Ns_ConnConstructHeaders	Put HTTP header into DString
Ns_ConnFlushHeaders	Mark the end of the headers
Ns_ConnOutputHeaders	Get Ns_Set of headers to send to client
Ns_ConnPrintfHeader	Return a formatted header
Ns_ConnReplaceHeaders	Replace output headers for connection
Ns_ConnSetExpiresHeader	Return an "expires" header for the given time
Ns_ConnSetHeaders	Set the value for a header field
Ns_ConnSetLastModifiedHeader	Return a last modified header using the given time
Ns_ConnSetLengthHeader	Return a Content-Length header
Ns_ConnSetRequiredHeaders	Return the required HTTP headers
Ns_ConnSetTypeHeader	Return a Content-Type header

HTTP Complete Response Functions

The following functions can be used to generate complete responses to HTTP requests.

Ns_ConnReturnAdminNotice	Return a short notice to a client to contact system administrator
Ns_ConnReturnData	Return an HTML string to a client
Ns_ConnReturnFile	Return a file to a client
Ns_ConnReturnHtml	Return an HTML string to a client
Ns_ConnReturnNotice	Return a short notice to a client
Ns_ConnReturnOpenFd	Return a file to a client
Ns_ConnReturnOpenFile	Return a file to a client
Ns_ConnReturnRedirect	Return an HTTP redirect response to a client
Ns_ConnReturnStatus	Return a status message to a client

HTTP Simple Response Functions

Often the only response required by the AOLserver is the HTTP status line. For example, after a successful PUT of a new file, the only required response is the status line to indicate if the file was successfully saved on the server. The following functions call Ns_ConnReturnStatus or Ns_ConnReturnNotice with the appropriate status code, reason, and/or notice message:

Ns_ConnReturnBadRequest	The request was invalid. Status = 400
Ns_ConnReturnForbidden	The request is forbidden. There is no Authorization header that will authorize access from this IP address. Status = 403
Ns_ConnReturnInternalError	A server internal error occurred. Status = 500
Ns_ConnReturnNoResponse	The request requires no response. Status = 204
Ns_ConnReturnNotFound	The requested URL was not found on the server. Status = 404
Ns_ConnReturnNotImplemented	The request has not been implemented by the server. Status = 500
Ns_ConnReturnNotModified	The requested data have not been modified since the time specified by the If-Modified-Since header sent by the client. Status = 304
Ns_ConnReturnOk	The request was successful. Status = 200
Ns_ConnReturnUnauthorized	The request did not include a valid Authorization header or the header did not specify an authorized user. Status = 401
Ns_ConnRunRequest	Execute procedure for method and URL pattern

HTTP Low-Level Connection Functions

The following functions can be used to send data directly to the client. No formatting or immediate buffering is done to the data.

Ns_ConnAuthPasswd	Return password
Ns_ConnAuthUser	Return user name
Ns_ConnClose	Close a connection
Ns_ConnContentLength	Return content length
Ns_ConnContentSent	Check if browser sent content
Ns_ConnCopyToChannel	Copy content to Tcl channel
Ns_ConnCopyToDString	Copy data from connection to dynamic string
Ns_ConnCopyToFd	Copy content to file descriptor
Ns_ConnCopyToFile	Copy data from connection to a file
Ns_ConnDriverContext	Return driver context
Ns_ConnDriverName	Return driver name
Ns_ConnFlushContent	Flush remaining content
Ns_ConnGetQuery	Construct Ns_Set representing query data
Ns_ConnGets	Read content into a buffer
Ns_ConnHeaders	Return headers
Ns_ConnHost	Return host
Ns_ConnInit	Run socket init procedure
Ns_ConnLocation	Return location
Ns_ConnModifiedSince	Determine if content modified since a specified date
Ns_ConnPeer	Return name of peer
Ns_ConnPeerPort	Return peer port
Ns_ConnPort	Return port
Ns_ConnPuts	Send a string to a client
Ns_ConnRead	Read content into buffer
Ns_ConnReadHeaders	Read headers into Ns_Set
Ns_ConnReadLine	Read a line from a connection
Ns_ConnRedirect	Perform internal redirect
Ns_ConnResponseLength	Return response length
Ns_ConnResponseStatus	Return response status
Ns_ConnReturnOpenChannel	Write Tcl channel content to conn
Ns_ConnSendChannel	Send Tcl channel content to conn
Ns_ConnSendDString	Write a DString to the conn
Ns_ConnSendFd	Write file to connection content
Ns_ConnSendFp	Write file to connection content
Ns_ConnServer	Return name of server
Ns_ConnWrite	Send data to a client
Ns_DriverEnableKeepalive	Enable HTTP Keepalive on driver
Ns_WriteConn	Send a specified length of data to the client

Logging Functions

The functions in this category are listed in the following table.

Ns_Fatal	Log a fatal error and shutdown
Ns_Log	Log formatted message
Ns_LogRoll	Roll server log
Ns_LogTime	Construct local date and time for log file
Ns_RollFile	Rename a file and increment its backup number

Memory Pool Functions

The functions in this category are listed in the following table:

Ns_PoolAlloc	Allocate memory within a pool
Ns_PoolCreate	Create a new memory pool
Ns_PoolDestroy	Destroy a memory pool
Ns_PoolDump	Debug a memory pool
Ns_PoolFree	Free pool memory
Ns_PoolRealloc	Reallocate pool memory
Ns_PoolTrace	Trace a memory pool
Ns_ThreadFree	Free thread pool memory
Ns_ThreadMalloc	Allocate thread pool memory
Ns_ThreadPool	Get thread pool memory
Ns_ThreadRealloc	Realloc thread pool memory

Mime-Related Functions

The functions in this category are listed in the following table.

Ns_GetMimeType

Get Mime type

Module Logging Realms Functions

The functions in this category are listed in the following table.

Ns_ModLog	Log a message with a realm
Ns_ModLogGetThreshold	Get the severity of the logging threshold of a handle
Ns_ModLogLookupHandle	Obtain the handle of a given realm
Ns_ModLogLookupRealm	Obtain the realm from the handle
Ns_ModLogRedirect	Redirect logging of a realm to a file
Ns_ModLogRegister	Register a new realm
Ns_ModLogSetThreshold	Set the logging severity of a handle

Scheduled Procedures Functions

These functions allow you to specify a procedure to be run daily, weekly, or at specified intervals

Function	Description
Ns_ScheduleDaily	Schedule a procedure to run once a day
Ns_ScheduleProc	Schedule a procedure to run at specified intervals (simplified options)
Ns_ScheduleProcEx	Schedule a procedure to run at specified intervals (expanded options)
Ns_ScheduleWeekly	Schedule a procedure to run once a week
Ns_UnscheduleProc	Stop a scheduled procedure

Sockets Interface Functions

The following functions are available for managing sockets. Developers should consult a book on socket programming when using these functions, for example "Unix Network Programming" by W. Richard Stevens.

Function	Description
Ns_BindSock	Bind a socket as root
Ns_GetSockAddr	Get socket driver address
Ns_SockAsyncConnect	Create a remote socket and return immediately
Ns_SockCallback	Register a socket callback function
Ns_SockCancelCallback	Remove a socket callback
Ns_SockConnect	Create a socket to remote host and port
Ns_SockListen	Create a socket on a specified address and port
Ns_SockListenCallback	Register a socket callback function and create socket
Ns_SockPipe	Return a pair of connected sockets
Ns_SockPortBound	Determine if port is bound
Ns_SockSetBlocking	Set a socket in blocking mode
Ns_SockSetNonBlocking	Set a socket in nonblocking mode
Ns_SockTimedConnect	Create a remote socket within a specified time

Socket Driver Interface Functions

The functions in this category are listed in the following table:

Ns_GetDriver	Get socket driver
Ns_GetDriverContext	Get socket driver context
Ns_GetDriverLabel	Get socket driver label
Ns_GetDriverName	Get socket driver name
Ns_GetDriverProc	Get a communications driver procedure
Ns_GetFirstDriver	Get pointer to first socket driver
Ns_GetNextDriver	Get pointer to next socket driver
Ns_QueueConn	Make a queue a new conn
Ns_RegisterDriver	Register a socket driver
Ns_RegisterLocation	Register location for socket driver
Ns_SetDriverProc	Set socket driver callback

Storage and Retrieval Functions

The functions in this category are listed in the following table. In rows where more than one function is listed, the preferred function is listed first.

Ns_ServerSpecificAlloc	Return unique integer to use in other functions
Ns_ServerSpecificDestroy	Delete server-specific data
Ns_ServerSpecificGet	Retrieve server-specific data
Ns_ServerSpecificSet	Store server-specific data for subsequent retrieval
Ns_TlsAlloc, Ns_AllocThreadLocalStorage	Allocate thread local storage
Ns_TlsGet, Ns_GetThreadLocalStorage	Get thread local storage
Ns_TlsSet, Ns_SetThreadLocalStorage	Set thread local storage
Ns_UrlSpecificAlloc	Return unique integer to use in other functions
Ns_UrlSpecificDestroy	Delete URL-specific data
Ns_UrlSpecificGet	Retrieve URL-specific data
Ns_UrlSpecificGetExact	Retrieve URL-specific data without inheritance
Ns_UrlSpecificSet	Store URL-specific data for subsequent retrieval

Synchronization Functions

Condition Variables

Condition variables are managed with the following functions

Ns_CondBroadcast	Wake up all threads waiting on a cond
Ns_CondDestroy	Free a cond's memory
Ns_CondInit	Initialize a cond
Ns_CondSignal	Wake up a single thread
Ns_CondTimedWait	Block on a cond
Ns_CondWait	Wait indefinitely on a cond

Semaphores

Semaphores are managed with the following functions. The preferred function is listed first in each row.

Ns_SemaDestroy, Ns_DestroySemaphore	Destroy a semaphore object
Ns_SemaInit, Ns_InitializeSemaphore	Initialize a semaphore object
Ns_SemaPost, Ns_ReleaseSemaphore	Increment a semaphore object
Ns_SemaWait, Ns_WaitForSemaphore	Wait for a semaphore object to be incremented above 0.

Mutexes

Mutexes are managed with the following functions. The preferred function is listed first in each row.

Ns_MutexDestroy, Ns_DestroyMutex	Destroy a mutex object
Ns_MutexInit, Ns_InitializeMutex	Initialize a mutex object
Ns_MutexLock, Ns_LockMutex	Lock a mutext object
Ns_MutexUnlock, Ns_UnlockMutex	Unlock a mutext object

Events

Events are managed with the following functions:

Ns_AbsTimedWaitForEvent	Wait for an event to be broadcast
Ns_BroadcastEvent	Wake all threads blocked in Ns_WaitForEvent.
Ns_DestroyEvent	Destory an event object.
Ns_InitializeEvent	Initialize an event object.
Ns_SetEvent	Wait no more than one thread blocked in Ns_WaitForEvent
Ns_TimedWaitForEvent	Wait for an event to be raised or a timeout.
Ns_UTimedWaitForEvent	Wait for an event for a specified time, in microseconds
Ns_WaitForEvent	Wait for an event to be raised.

Critical Sections

Critical sections are managed with the following functions. The preferred function is listed first in each row.

Ns_CsDestroy, Ns_DestroyCriticalSection	Destroy a critical section object
Ns_CsEnter, Ns_EnterCriticalSection	Enter a critical section of code
Ns_CsInit, Ns_InitializeCriticalSection	Initialize a critical section object
Ns_CsLeave, Ns_LeaveCriticalSection	Leave a critical section of code

Read/write Locks

Read/write locks are managed with the following functions. The preferred function is listed first in each row.

Ns_RWLockDestroy, Ns_DestroyRWLock	Destroy a read/write lock
Ns_RWLockInit, Ns_InitializeRWLock	Initialize a read/write lock
Ns_RWLockRdLock, Ns_ReadLockRWLock	Acquire a read lock
Ns_RWLockUnlock, Ns_ReadUnlockRWLock, Ns_WriteUnlockRWLock	Release a read/write lock
Ns_RWLockWrLock, Ns_WriteLockRWLock	Acquire a write lock

Thread Interface Functions

The following functions are used to support platform independent multithreaded programming. A table following this list of functions points you to further information for each function.

Ns_CheckStack	Check for thread stack overflow
Ns_Fork	Perform a fork
Ns_GetThread	Get the thread object of the current thread.
Ns_GetThreadId	Get a unique integer ID for the current thread.
Ns_ThreadCreate, Ns_BeginThread, Ns_BeginDetachedThread	Create new thread
Ns_ThreadExit, Ns_ExitThread	Free or exit thread
Ns_ThreadGetName	Get thread name
Ns_ThreadId	Get thread ID
Ns_ThreadJoin, Ns_WaitThread, Ns_WaitForThread	Wait for thread exit
Ns_ThreadSelf	Get handle to thread
Ns_ThreadSetname	Set thread name
Ns_ThreadYield	Put the current thread to sleep momentarily, allowing other threads to run,
Ns_WaitForProcess	Wait for process to exit
Ns_WaitForStartup	Block until server startup
Ns_WaitProcess	Wait for process to exit

The following table tells you what to look under in your vendor-specific documentation for more information on threaded programming with respect to each function.

Function	Solaris	pthread	SGI sproc (2)
Threads:
Ns_ThreadCreate	thr_create	pthread_create	sproc (4)
Ns_ThreadJoin	thr_join	pthread_join (3)	waitpid
Ns_GetThreadId	thr_self	pthread_self	getpid
Mutexes:
Ns_MutexInit	mutex_int	pthread_mutex_init	usnewlock
Ns_MutexDestroy	mutex_destroy	pthread_mutex_des-troy	usfreelock
Ns_MutexLock	mutex_lock	pthread_mutex_lock	ussetlock
Ns_MutexUnlock	mutex_unlock	pthread_mutex_un-lock	usunsetlock
Semaphores:
Ns_SemaInit	sema_int	(5)	usnewsema
Ns_SemaDestroy	sema_destroy	(5)	usfreesema
Ns_SemaWait	sema_wait	(5)	uspsema
Ns_SemaPost	sema_post	(5)	usvsema
Events:
Ns_InitializeEvent	cond_int	pthread_cond_init	(6)
Ns_DestroyEvent	cond_destroy	pthread_cond_destroy	(6)
Ns_WaitForEvent	cond_wait	pthread_cond_wait	sigtimedwait
Ns_TimedWaitForEvent	cond_timedwait	pthread_cond_timed-wait	sigtimedwait
Ns_SetEvent	cond_signal	pthread_cond_signal	kill
Ns_BroadcastEvent	cond_broadcast	pthread_cond_broad-cast	kill
Critical Sections:
Ns_CsInit	(10)	pthread_mutex_init (10)	(10)
Ns_CsDestroy	(10)	pthread_mutex_de-stroy	(10)
Ns_CsEnter	(10)	pthread_mutex_lock	(10)
Ns_CsLeave	(10)	pthread_mutex_un-lock	(10)
Ns_TlsAlloc	thr_keycreate	pthread_keycreate	(11)
Ns_TlsSet	thr_setspecific	pthread_setspecific	(11)
Ns_TlsGet	thr_getspecific	pthread_getspecific	(11)

Notes:

(2) Threads on SGI Irix 5.3 are implemented as a process group with all attributes shared. As such, threads will show up as separate processes in a process listing using the ps command. Note, however, that although the server is implemented with multiple processes, it is still multithreaded in all respects (e.g., a single address space, open file table, etc.). In addition, if one process dies unexpectantly (e.g., core dump or on receiving a kill -9), the other processes will be notified and immediately exit. On Irix 6.2, you may run the 5.3 share group version (nsd binary) or a newer pthreads interface binary (nsdp).

(3) The pthread_join routine would allow multiple threads to wait for a single thread to exit on pthreads. However, in the nsthread library, only a single thread may wait using the Ns_ThreadJoin function.

(4) To allow any thread to wait for any other thread as in other multithreaded platforms, the SGI Irix threads interface uses a thread manager process which actually performs the sproc and waitpid calls on behalf of the other process threads.

(5) Pthreads does not include a semaphore and is emulated with a mutex and condition variable.

(6) SGI Irix does not include an event object and is emulated with ordinary process signals and the sigtimedwait and kill system calls.

(7) Nsthread events are emulated with pthread condition variables.

(10) Critical sections are emulated with a mutex and a condition variable.

(11) Thread local storage is not available on SGI sproc and is emulated using the PRDA, the process data area, as defined in the sys/prcnt.h header.

Tcl Interpreter Functions

The following functions are used to manipulate Tcl interpreters.

Ns_GetConnInterp	Get the Tcl interpreter for the connection
Ns_TclAllocateInterp	Allocate a Tcl interpreter for a server
Ns_TclDeAllocateInterp	Perform cleanup after deallocating a Tcl interpreter
Ns_TclDestroyInterp	Mark Tcl interpreter for deletion
Ns_TclInitInterps	Call a Tcl init procedure in the parent interpreter
Ns_TclInterpServer	Return name of server
Ns_TclMarkForDelete	Mark Tcl interpreter for deletion

Miscellaneous Functions

The following are miscellaneous utility functions in the AOLserver C API.

Ns_AdjTime	Adjust Ns_Time
Ns_Asctime	Perform asctime_r
Ns_CloseOnExec	Set close-on-exec flag
Ns_Ctime	Perform ctime_r
Ns_DiffTime	Get difference between two times
Ns_DupHigh	Move file descriptors
Ns_Encrypt	Encrypt a password in the form used by the Unix /etc/passwd file and the nsperm module.
Ns_ExecArgblk	Execute file with argument string
Ns_ExecArgv	Execute file with argument array
Ns_ExecProc	Execute file with argument array
Ns_ExecProcess	Execute file with argument string
Ns_FetchPage	Copy data from URL to dynamic string
Ns_FetchURL	Fetch a remote URL.
Ns_GetHostByAddr	Convert an IP address to a hostname
Ns_GetTime	Perform gettimeofday
Ns_GetUid	Return UID of user
Ns_GetUserHome	Get Unix user's home directory
Ns_Gmtime	Perform gmtime
Ns_HttpTime	Return a formatted time string
Ns_HtuuDecode	Perform base64 decode
Ns_HtuuEncode	Perform base64 encode
Ns_IncrTime	Increment time by seconds and microseconds
Ns_InetNtoa	Perform inet_ntoa
Ns_InfoBootTime	Return server boot time
Ns_InfoBuildDate	Return AOLserver build date
Ns_InfoConfigFile	Return full path name of the configuration file in use.
Ns_InfoErrorLog	Return error log name
Ns_InfoHomePath	Return directory where the AOLserver is installed.
Ns_InfoHostname	Return hostname of server
Ns_InfoLabel	Return source code label of server
Ns_InfoPid	Return server pid
Ns_InfoPlatform	Return platform
Ns_InfoServerName	Return AOLserver name string ("AOLserver").
Ns_InfoServersStarted	Determine if server has started
Ns_InfoServerVersion	Return AOLserver version string.
Ns_InfoShutdownPending	Determine if a server shutdown is pending
Ns_InfoStarted	Determine if server has started
Ns_InfoUptime	Return time server has been running
Ns_LibPath	Construct path relative to lib
Ns_Localtime	Perform localtime
Ns_Match	Compare two strings
Ns_ModuleLoad	Load a module into AOLserver
Ns_ModuleSymbol	Return symbol
Ns_NextWord	Find next word in string
Ns_PageRoot	Return path name of the AOLserver pages directory for a server.
Ns_ParseHeader	Parse Http headers
Ns_ParseHttpTime	Convert Http time into time_t
Ns_ParseUrl	Parse a URL
Ns_QuoteHtml	Quote an HTML string
Ns_Readdir	Perform readdir
Ns_Sigmask	Perform sigprocmask
Ns_Signal	Install signal handler
Ns_Sigwait	Perform sigwait
Ns_StrCaseFind	Perform strstr
Ns_StrToLower	Lowercase string
Ns_StrToUpper	Uppercase string
Ns_StrTrim	Trim string
Ns_StrTrimLeft	Trim blanks from left
Ns_StrTrimRight	Trim blanks from right
Ns_StringPrint	Print string
Ns_Strtok	Perform strtok_r
Ns_TclEval	Execute a Tcl script
Ns_TclGetConn	Get connection
Ns_TclGetOpenChannel	Get open channel in interpreter
Ns_TclGetOpenFd	Get open file descriptor
Ns_TclInitModule	Source Tcl module before server startup
Ns_TclLibrary	Return private Tcl directory
Ns_TclLogError	Write errorInfo to the log file
Ns_TclAppendInt	Append integer to Tcl result
Ns_TclRegisterAtCreate	Register function for interpreter creation
Ns_TclRegisterDeferred	Register function for interpreter cleanup

Database Functions

The AOLserver provides several functions for accessing the database. These include convenient routines for sending DML and DDL SQL statements or SQL statements that return rows from the database. (DML stands for Data Manipulation Language and includes SQL statements to insert, update, and delete data. DDL stands for Data Definition Language and includes SQL statements to create tables and views.)

There are also powerful catalog functions that help you build custom responses based on the schema of the tables within the database. These functions are only available if the nsdb module is loaded.

The following groups of database functions are described in the following subsections.

Pool Functions	Functions used to obtain information about database pools and obtain handles to database pools.
SQL Query Functions	Functions used to send queries to the database and process the results
Stored Procedure Functions	Functions used to run stored procedures.
Miscellaneous Functions	Miscellaneous functions associated with the database.

Pool Functions

The functions in this category are listed in the following table.

Ns_DbBouncePool	Mark all database handles stale
Ns_DbPoolAllowable	Determine if pool is available
Ns_DbPoolDefault	Get default pool
Ns_DbPoolDescription	Get pool description
Ns_DbPoolGetHandle	Get database handle from pool
Ns_DbPoolGetMultipleHandles	Get multiple database handles from pool
Ns_DbPoolList	Get a list of available pools for a server
Ns_DbPoolPutHandle	Release a database handle for a pool
Ns_DbPoolTimedGetHandle	Get database handle from pool with timeout
Ns_DbPoolTimedGetMultipleHandles	Get multiple database handles from pool with timeout

SQL Query Functions

The AOLserver C Database API includes the following functions for sending queries to the database and processing the results. Rows are returned as Ns_Set structures described earlier.

Ns_Db0or1Row	Execute an SQL statement that must return <= 1 row
Ns_Db1Row	Execute an SQL statement that must return one row
Ns_DbBindRow	Return an Ns_Set structure of columns returned by the previously-executed SQL command
Ns_DbCancel	Cancel an active SQL select statement
Ns_DbDML	Execute an SQL DML statement
Ns_DbExec	Execute an SQL command
Ns_DbFlush	Flush any waiting rows
Ns_DbGetRow	Fetch the next waiting row after an Ns_DbSelect
Ns_DbInterpretSqlFile	Parse DML statements and send to database
Ns_DbSelect	Send a row-generating query to the database

Stored Procedure Functions

The following functions handle stored procedures.

Ns_DbSpExec	Run a stored procedure
Ns_DbSpGetParams	Get output parameters from stored procedure
Ns_DbSpReturnCode	Get return code from stored procedure
Ns_DbSpSetParam	Set input parameter for stored procedure
Ns_DbSpStart	Start execution of a stored procedure

Miscellaneous Functions

The following functions provide additional ways to manipulate the database.

Ns_DbDriverDbType	Get database type
Ns_DbDriverName	Get driver for database
Ns_DbQuoteValue	Adds extra single quote to single quotes in string
Ns_DbRegisterDriver	Register database driver with the server
Ns_DbSetException	Set last error message for database