AOLserver

# Operating System C Library Functions

$Header: /cvsroot/aolserver/aolserver.com/docs/devel/c/index.html,v 1.1 2002/03/07 19:15:35 kriston Exp $

## Ns_AdjTime

Adjust Ns_Time.

### Syntax

        Ns_AdjTime(
        Ns_Time *timePtr
        );

### Description

Adjust an Ns_Time so that the values are in range. If usec is negative, sec is decremented; if usec is over 1000000, sec is incremented.

## Ns_Asctime

Perform asctime_r

### Syntax

        char* Ns_Asctime (
        const struct tm* tmPtr
        );

### Description

This function is a wrapper around asctime_r(3C). This converts a tm struture to a 26-character string. The value returned by this function will be changed by additional calls to it within the same thread, so make a copy of the value if needed.

## Ns_Calloc

Allocate a zero-filled block of memory

### Syntax

        void *Ns_Calloc(
        size_t num,
        size_t size
        );

### Description

The Ns_Calloc function allocates a block of zero-filled memory large enough to hold the given number of elements of the given size. This function replaces the system calloc function.

## Ns_CheckStack

Check for thread stack overflow

### Syntax

       int Ns_CheckStack (void);

### Description

Check for possible thread stack overflow. This function returns NS_OK if stack appears ok, otherwise it returns NS_ERROR.

## Ns_CloseOnExec

Set close-on-exec flag

### Syntax

        int Ns_CloseOnExec (
        int fd
        );

### Description

Set the close-on-exec flag on a file descriptor.

## Ns_Ctime

Perform ctime_r

### Syntax

        char* Ns_Ctime (
        const time_t* clock
        );

### Description

This function is a wrapper around ctime_r(3C).

## Ns_DiffTime

Get difference between two times

### Syntax

        void Ns_DiffTime (
        Ns_Time* t1,
        Ns_Time* t2,
        Ns_Time* result
        );

### Description

Determine the difference in seconds between two Ns_Time structures. The result is put into result.

## Ns_DupHigh

Move file descriptors

### Syntax

        Ns_DupHigh(
        int *fd
        );

### Description

Ns_DupHigh moves file descriptors above 256 on platforms where the file descriptor in the stdio FILE structure is an unsigned char. By calling Ns_DupHigh on file descriptors that you know will not be buffered, you can leave as many low file descriptors available for stdio as possible. Ns_DupHigh is not supported on platforms where this is not an issue.

## Ns_ExecArgblk

Execute file with argument string

### Syntax

        int Ns_ExecArgblk (
        char* sExec,
        char* sDir,
        int fdIn,
        int fdOut,
        char* argBlk,
        Ns_Set* env
        );

### Description

Change current directory to sDir if it is not NULL and executes the file sExec. All input will come from fdIn if it's greater than 0; otherwise stdin will be used. All output will go to fdOut if it's greater than 0; otherwise stdout will be used.

The argBlk is a string of null-separated arguments, terminated with two nulls, like this: "foo\0bar\0\0".

The env is an Ns_Set containing environment variables to pass the program.

## Ns_ExecArgv

Execute file with argument array

### Syntax

        int Ns_ExecArgv (
        char* sExec,
        char* sDir,
        int fdIn,
        int fdOut,
        char** argv,
        Ns_Set* env
        );

### Description

Change current directory to sDir if it is not NULL and executes the file sExec. All input will come from fdIn if it's greater than 0; otherwise stdin will be used. All output will go to fdOut if it's greater than 0; otherwise stdout will be used.

The argv is a null-terminated array of argument strings, like this: { "foo", "bar", NULL }.

The env is an Ns_Set containing environment variables to pass the program.

## Ns_ExecProc

Execute file with argument array

### Syntax

        int Ns_ExecProc (
        char* sExec,
        char** argv
        );

### Description

Execute the file sExec. All input will come from stdin. All output will go to stdout.

The argv is a null-terminated array of argument strings, like this: { "foo", "bar", NULL }.

## Ns_ExecProcess

Execute file with argument string

### Syntax

        int Ns_ExecProcess (
        char* sExec,
        char* sDir,
        int fdIn,
        int fdOut,
        char* argBlk,
        Ns_Set* env
        );

### Description

Change current directory to sDir if it is not NULL and executes the file sExec. All input will come from fdIn if it's greater than 0; otherwise stdin will be used. All output will go to fdOut if it's greater than 0; otherwise stdout will be used.

The argBlk is a string of null-separated arguments, terminated with two nulls, like this: "foo\0bar\0\0".

The env is an Ns_Set containing environment variables to pass the program.

## Ns_Fatal

Log a fatal error and shutdown

### Syntax

        void Ns_Fatal(
        char *fmt,
        ...
        );

### Description

This function calls Ns_Log with the Fatal severity and then shuts down the server.

## Ns_Fork

Perform a fork

### Syntax

        int Ns_Fork (void);

### Description

Performs a fork(), or on Solaris, fork1().

## Ns_Free

Free a block of allocated memory

### Syntax

        void *Ns_Free(
        void *buf
        );

### Description

The Ns_Free function frees any memory allocated by the Ns_Malloc, Ns_Calloc, or Ns_Realloc functions. This function replaces the system free function.

## Ns_GetTime

Perform gettimeofday

### Syntax

        void Ns_GetTime (
        Ns_Time*
        );

### Description

This function is a wrapper for gettimeofday(3B).

## Ns_GetUid

Return UID of user

### Syntax

        int Ns_GetUid (
        char* user
        );

### Description

Returns the Unix UID of the user running the server.

## Ns_GetUserHome

Get UNIX user's home directory

### Syntax

        int Ns_GetUserHome(
        Ns_DString *pds,
        char *user
        );

### Description

The Ns_GetUserHome function returns NS_TRUE and appends the user's home directory to the Ns_DString passed in, or it returns NS_FALSE if the user doesn't exist.

## Ns_Gmtime

Perform gmtime

### Syntax

        struct tm* Ns_Gmtime (
        const time_t* clock
        );

### Description

This function is a wrapper for gmtime(3C).

## Ns_HomePath

Construct a path name relative to the AOLserver home directory

### Syntax

        char *Ns_HomePath(
        Ns_DString * dest,
        char *relpath
        );

### Description

The Ns_HomePath function constructs a path name by appending the given relative path to the AOLserver home directory. The resulting path name is appended to the given Ns_DString.

## Ns_HttpTime

Return a formatted time string

### Syntax

        char *Ns_HttpTime(
        Ns_DString *pds
        time_t *when
        );

### Description

The Ns_HttpTime function converts given time to the appropriate format for an HTTP header or log file. The Ns_HttpTime function returns the time and date with a four digit year, e.g., "Sun, 06 Nov 1994 08:49:37 GMT".

If when is NULL, the function returns a string containing the current time. The formatted time string is appended to the specified Ns_DString (pds).

## Ns_IncrTime

Increment time by seconds and microseconds

### Syntax

        void Ns_IncrTime (
        Ns_Time* time,
        time_t sec,
        long usec
        );

### Description

Increment time by sec.usec, where usec is microseconds.

## Ns_InetNtoa

Perform inet_ntoa

### Syntax

        char* Ns_InetNtoa (
        struct in_addr addr
        );

### Description

This function wraps inet_ntoa(3N).

## Ns_InfoBootTime

Return server boot time

### Syntax

       int Ns_InfoBootTime (void);

### Description

Return the time (in time_t form) of the most recent server boot.

## Ns_InfoBuildDate

Return AOLserver build date

### Syntax

        char *Ns_InfoBuildDate(void);

### Description

The Ns_InfoBuildDate function returns the date and time AOLServer was compiled.

## Ns_InfoConfigFile

Return full path name of the configuration file in use.

### Syntax

        char *Ns_InfoConfigFile(void)

### Description

Return full path name of the configuration file in use.

## Ns_InfoErrorLog

Return error log name

### Syntax

        char* Ns_InfoErrorLog (void);

### Description

Return the name of the error log.

## Ns_InfoHomePath

Return directory where the AOLserver is installed.

### Syntax

        char *Ns_InfoHomePath(void)

### Description

Return directory where the AOLserver is installed.

## Ns_InfoHostname

Return hostname of server

### Syntax

        char* Ns_InfoHostname (void);

### Description

Return the hostname that AOLserver thinks it's running on, as specified in the configuration file.

## Ns_InfoLabel

Return source code label for server

### Syntax

        char *Ns_InfoLabel(void);

### Description

Returns the source code label for the server. If no label was used, "unlabeled" is returned. You can use these functions to provide the source code label when you report problems with the server.

## Ns_InfoPid

Return server pid

### Syntax

        int Ns_InfoPid (void);

### Description

Return pid of AOLserver.

## Ns_InfoPlatform

Return platform

### Syntax

        char* Ns_InfoPlatform (void);

### Description

Returns platform name, e.g. "IRIX".

## Ns_InfoServerName

Return AOLserver name string ("AOLserver").

### Syntax

        char *Ns_InfoServerName(void)

### Description

Return AOLserver name string ("AOLserver").

## Ns_InfoServersStarted

Determine if server has started

### Syntax

        int Ns_InfoServersStarted (void);

### Description

Return TRUE if the server has started, i.e., if initialization and module loading is complete.

## Ns_InfoServerVersion

Return AOLserver version string.

### Syntax

        char *Ns_InfoServerVersion(void)

### Description

Return AOLserver version string.

## Ns_InfoShutdownPending

Determine if a server shutdown is pending

### Syntax

        int Ns_InfoShutdownPending (void);

### Description

Return TRUE if there is there a shutdown pending, i.e., if an INTR signal has been received or if ns_shutdown has been called.

## Ns_InfoStarted

Determine if server has started

### Syntax

        int Ns_InfoStarted (void);

### Description

Return TRUE if the server has started, i.e., if initialization and module loading is complete.

## Ns_InfoUptime

Return time server has been running

### Syntax

        int Ns_InfoUptime (void);

### Description

Return how long, in seconds, AOLserver has been running.

## Ns_LibPath

Construct path relative to lib

### Syntax

        char* Ns_LibPath (Ns_DString* dest,...);

### Description

Make a path relative to $ASHOME/lib/ given the specified destination. For example, if AOLserver is running out of /disk2/aolserver, the following call would return "/disk2/aolserver/lib/foo/bar": Ns_LibPath("foo", "bar", NULL);

## Ns_Localtime

Perform localtime

### Syntax

        struct tm* Ns_Localtime (
        const time_t* clock
        );

### Description

This function wraps localtime(3C).

## Ns_Log

Log formatted message

### Syntax

        void Ns_Log(
        Ns_LogSeverity severity,
        char *fmt,
        ...
        );

### Description

The Ns_Log function writes formatted messages to the server log file. Allowable values for severity are:

Notice

Something interesting occurred.

Warning

Maybe something bad occurred.

Error

Something bad occurred.

Fatal

Something extremely bad occurred. The server will shut down after logging this message.

Bug

Something occurred that implies there is a bug in your code.

Debug

If the server is in Debug mode, the message is printed. Debug mode is specified in the [ns/parameters] section of the configuration file. If the server is not in debug mode, the message is not printed.

### Examples

        char *hServer; /* server handle */
        char *hModule; /* module handle */
        Ns_Log(Notice, "Initializing module %s on server %s",
                                            hModule, hServer);

## Ns_LogRoll

Roll server log

### Syntax

        int Ns_LogRoll (void);

### Description

Roll the server.log file, renaming the existing file with the date and starting a new log file.

## Ns_LogTime

Construct local date and time for log file

### Syntax

        char *Ns_LogTime(
        char *dateTimeBuf
        );

### Description

The Ns_LogTime function constructs the local date and time for use in the log file. Upon completion, dateTimeBuf will contain the formatted string. Ns_LogTime is used by Ns_Log to create log file entries.

## Ns_MakePath

Construct a path name from a list of path elements

### Syntax

        char *Ns_MakePath(
        Ns_DString * dest,
        ...
        );

### Description

The Ns_MakePath function constructs a path name by appending a list of path elements to the given Ns_DString. The path elements are separated by single slashes, and the resulting path name is appended to the given Ns_DString. The last argument needs to be NULL to indicate the end of the argument list.

## Ns_Malloc

Allocate a block of memory

### Syntax

        void *Ns_Malloc(
        size_t size
        );

### Description

The Ns_Malloc function returns a block of memory of the given size. This function replaces the system malloc function.

## Ns_ModuleLoad

Load a module into AOLserver

### Syntax

        int Ns_ModuleLoad(
        char *hServer,
        char *hModule,
        char *sModuleFile,
        char *sInitProc
        );

### Description

The Ns_ModuleLoad function loads a module into AOLserver and calls the initialization routine (sInitProc). If sInitProc is NULL, the initialization routine used defaults to Ns_ModuleInit.

## Ns_ModulePath

Construct a path from base path

### Syntax

        char *Ns_ModulePath(
        Ns_DString *dest,
        char *hServer,
        char *hModule,
        ...
        );

### Description

The Ns_ModulePath function constructs a path by appending the final variable arguments to the base path defined by a module on the specified server. The list of arguments must end with NULL.

## Ns_ModuleSymbol

Return symbol

### Syntax

        int Ns_ModuleSymbol(
        char *sModuleFile,
        char *sSymbolName
        );

### Description

The Ns_ModuleSymbol function returns a pointer to the value of a symbol in a particular shared library.

## Ns_NormalizePath

Normalize a path name

### Syntax

        char *Ns_NormalizePath(
        Ns_DString *dest,
        char *path
        );

### Description

This function removes any extraneous slashes from the path and resolves "." and ".." references. The result is appended to the given Ns_DString. For example Ns_NormalizePath(&ds, "/dog/cat/../../rat/../../dog//mouse/.."); appends "/dog" to the Ns_DString.

## Ns_PageRoot

Return path name of the AOLserver pages directory for a server.

### Syntax

        char *Ns_PageRoot(
        char *hServer
        );

### Description

Return path name of the AOLserver pages directory for a server.

## Ns_ParseHttpTime

Convert Http time into time_t

### Syntax

        time_t Ns_ParseHttpTime (
        char* str
        );

### Description

Convert a time like "Thursday, 10-Jun-93 01:29:59 GMT" or "Thu, 10 Jan 1993 01:29:59 GMT" into time_t.

## Ns_PathIsAbsolute

Check for an absolute path name

### Syntax

        int Ns_PathIsAbsolute(
        char *path
        );

### Description

This function returns 1 if the path is absolute and 0 otherwise. Under Unix, an absolute path starts with a `/'.

## Ns_PoolAlloc

Allocate memory within a pool

### Syntax

        void* Ns_PoolAlloc (
        Ns_Pool* pool,
        unsigned int size
        );

### Description

Alloc memory within a pool. Memory pools are thread-specific memory that reduce the number of globally-locking malloc(3C) calls.

## Ns_PoolCreate

Create a new memory pool

### Syntax

        Ns_Pool* Ns_PoolCreate (
        char* name
        );

### Description

Create a new memory pool with the specified name.

## Ns_PoolDestroy

Destroy a memory pool

### Syntax

        void Ns_PoolDestroy (
        Ns_Pool* pool
        );

### Description

Destroy the specified memory pool.

## Ns_PoolDump

Debug a memory pool

### Syntax

        void Ns_PoolDump (
        int fd,
        Ns_Pool* pool
        );

### Description

Write information about the pool to the open file descriptor fd.

## Ns_PoolFree

Free pool memory

### Syntax

        void Ns_PoolFree (
        Ns_Pool* pool,
        void* ptr
        );

### Description

Free pool memory.

## Ns_PoolRealloc

Reallocate pool memory

### Syntax

        void* Ns_PoolRealloc (
        Ns_Pool* pool,
        void* ptr,
        unsigned int size
        );

### Description

Perform realloc for pools. See the realloc(3C) man page.

## Ns_PoolTrace

Trace a memory pool

### Syntax

        int Ns_PoolTrace (
        char* filename
        );

### Description

Open the specified filename to contain debugging information and begin debugging. Returns NS_OK or NS_ERROR

## Ns_Readdir

Perform readdir

### Syntax

        struct dirent* Ns_Readdir (
        DIR* pDir
        );

### Description

This funciton wraps readdir(3B).

## Ns_Realloc

Resize a previously allocated block of memory

### Syntax

        void *Ns_Realloc(
        void *buf,
        size_t size
        );

### Description

The Ns_Realloc function reallocates a block of memory previously allocated with Ns_Malloc or Ns_Calloc to the given size. The block of memory may or may not move as a result. This function replaces the system realloc function.

## Ns_RollFile

Rename a file and increment its backup number

### Syntax

        int Ns_RollFile(
        char *filename,
        int backupMax
        );

### Description

The Ns_RollFile function renames the specified file, incrementing its backup number (file extension). The backupMax argument must be between 1 and 1000. Ns_RollFile returns a status of NS_ERROR or NS_OK.

## Ns_SetUrlToFileProc

Customize relative file mapping

### Syntax

        void Ns_SetUrlToFileProc(
        char *hserver,
        Ns_UrlToFileProc *proc
        );

### Description

Ns_SetUrlToFileProc() sets the procedure pointed to by proc to be called by Ns_UrlToFile() to map a URL to a file pathname. The interface of the procedure pointed to by proc must have the same interface as Ns_UrlToFile().

A NULL proc argument to Ns_SetUrlToFileProc() causes Ns_UrlToFile() afterwards to call a default procedure.

### Examples

        int
        Ns_ModuleInit(char *hServer, char *hModule)
        {
            Ns_SetUrlToFileProc(hServer, AliasedUrlToFile);

            return NS_OK;
        }

        static int
        AliasedUrlToFile(Ns_DString *dest, char *hServer, char *relpath)
        {
            char   *pageRoot;

            /*
             * construct dest from hServer and relpath
             */

            pageRoot = Ns_PageRoot(hServer);
            Ns_MakePath(dest, pageRoot, relpath, NULL);

            return NS_OK;
        }

       See the alias C example for a more comprehensive example.

## Ns_SetUserAuthorizeProc

Set function used by Ns_AuthorizeUser

### Syntax

        void Ns_SetUserAuthorizeProc(
        Ns_UserAuthorizeProc *procPtr
        );

### Description

Sets a procedure to handle calls to Ns_AuthorizeUser. This function should only be called once per execution of AOLserver. The procPtr should be of the form: typedef int (Ns_UserAuthorizeProc) (char *user, char *passwd); It should return NS_OK on a match or NS_ERROR if any problem is encountered or the password does not match.

## Ns_Sigmask

Perform sigprocmask

### Syntax

        int Ns_Sigmask (
        int how,
        sigset_t* set,
        sigset_t* oset
        );

### Description

This function wraps sigprocmask(2).

## Ns_Signal

Install signal handler

### Syntax

        int Ns_Signal (
        int sig, void (*proc) (void)
        );

### Description

Install a handler for a signal. This function is essentially a wrapper around signal(2).

## Ns_Sigwait

Perform sigwait

### Syntax

        int Ns_Sigwait (
        sigset_t* set,
        int* sig
        );

### Description

This function wraps sigwait(3).

## Ns_UrlIsDir

Check if a directory that corresponds to a URL exists

### Syntax

        int Ns_UrlIsDir(
        char *hServer,
        char *URL
        );

### Description

The Ns_UrlIsDir function constructs a directory name by appending the URL to the current AOLserver pages directory for the specified server. It returns 1 if the directory exists.

### Examples

       See the example for Ns_UrlIsFile.

## Ns_UrlIsFile

Check if a file that corresponds to a URL exists

### Syntax

        int Ns_UrlIsFile(
        char *hServer,
        char *URL
        );

### Description

The Ns_UrlIsFile function constructs a file name by appending the URL to the current AOLserver pages directory for the specified server. It returns 1 if the file exists and is a regular file.

### Examples

        /* IsFile - Simple request to determine if an URL is a file. */
        int
        IsFile(Ns_Conn *conn, void *ctx)
        {
            int isfile;
            char *server;

            server = Ns_ConnServer(conn);
            isfile = Ns_UrlIsFile(server, conn->request->url);
            if (isfile) {
                    Ns_ConnReturnNotice(conn, 200, "File", NULL);
            } else {
                    Ns_ConnReturnNotice(conn, 200, "Not a File", NULL);
            }
            return NS_OK;
        }

## Ns_UrlToFile

Construct the filename that corresponds to a URL

### Syntax

        int Ns_UrlToFile(
        Ns_DString *dest,
        char *hServer,
        char *URL
        );

### Description

The Ns_UrlToFile function writes the full path name of the file corresponding to the given URL. The result is appended to the Ns_DString. The function does not check that the file exists or is readable by the AOLserver process. This function returns a status of NS_OK or NS_ERROR.

### Examples

        /* A simple page fetch request function. */
        int
        SimpleFetch(Ns_Conn *conn, void *ctx)
        {
            Ns_DString ds;
            FILE fp;
            char *server;

            Ns_DStringInit(&ds);
            server = Ns_ConnServer(conn);
            Ns_UrlToFile(&ds, server, conn->request->url);
            fp = fopen(ds.string, "r");
            Ns_ConnSendOpenFp(conn, fp, -1);
            fclose(fp);
            Ns_DStringFree(&ds);
            return NS_OK;
        }

## Ns_WaitForProcess

Wait for process to exit

### Syntax

        int Ns_WaitForProcess (
        int iPid,
        int* pExitCode
        );

### Description

Wait for a proess to exit and write information about the process to the log. This function is essentially a wrapper around waitpid(2). It returns NS_OK if the process exited normally.

## Ns_WaitProcess

Wait for process to exit

### Syntax

        int Ns_WaitProcess (
        int iPid,
        );

### Description

Wait for a proess to exit and write information about the process to the log. This function is essentially a wrapper around waitpid(2). It returns NS_OK if the process exited normally.