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 $
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.
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.
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.
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.
Set close-on-exec flag
Syntax
int Ns_CloseOnExec (
int fd
);
Description
Set the close-on-exec flag on a file descriptor.
Perform ctime_r
Syntax
char* Ns_Ctime (
const time_t* clock
);
Description
This function is a wrapper around ctime_r(3C).
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.
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.
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.
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.
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 }.
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.
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.
Perform a fork
Syntax
int Ns_Fork (void);
Description
Performs a fork(), or on Solaris, fork1().
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.
Perform gettimeofday
Syntax
void Ns_GetTime (
Ns_Time*
);
Description
This function is a wrapper for gettimeofday(3B).
Return UID of user
Syntax
int Ns_GetUid (
char* user
);
Description
Returns the Unix UID of the user running the server.
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.
Perform gmtime
Syntax
struct tm* Ns_Gmtime (
const time_t* clock
);
Description
This function is a wrapper for gmtime(3C).
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.
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).
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.
Perform inet_ntoa
Syntax
char* Ns_InetNtoa (
struct in_addr addr
);
Description
This function wraps inet_ntoa(3N).
Return server boot time
Syntax
int Ns_InfoBootTime (void);
Description
Return the time (in time_t form) of the most recent server boot.
Return AOLserver build date
Syntax
char *Ns_InfoBuildDate(void);
Description
The Ns_InfoBuildDate function returns the date and time AOLServer was
compiled.
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.
Return error log name
Syntax
char* Ns_InfoErrorLog (void);
Description
Return the name of the error log.
Return directory where the AOLserver is installed.
Syntax
char *Ns_InfoHomePath(void)
Description
Return directory where the AOLserver is installed.
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.
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.
Return server pid
Syntax
int Ns_InfoPid (void);
Description
Return pid of AOLserver.
Return platform
Syntax
char* Ns_InfoPlatform (void);
Description
Returns platform name, e.g. "IRIX".
Return AOLserver name string ("AOLserver").
Syntax
char *Ns_InfoServerName(void)
Description
Return AOLserver name string ("AOLserver").
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.
Return AOLserver version string.
Syntax
char *Ns_InfoServerVersion(void)
Description
Return AOLserver version string.
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.
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.
Return time server has been running
Syntax
int Ns_InfoUptime (void);
Description
Return how long, in seconds, AOLserver has been running.
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);
Perform localtime
Syntax
struct tm* Ns_Localtime (
const time_t* clock
);
Description
This function wraps localtime(3C).
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);
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 `/'.
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.
Create a new memory pool
Syntax
Ns_Pool* Ns_PoolCreate (
char* name
);
Description
Create a new memory pool with the specified name.
Destroy a memory pool
Syntax
void Ns_PoolDestroy (
Ns_Pool* pool
);
Description
Destroy the specified memory pool.
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.
Free pool memory
Syntax
void Ns_PoolFree (
Ns_Pool* pool,
void* ptr
);
Description
Free pool memory.
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.
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
Perform readdir
Syntax
struct dirent* Ns_Readdir (
DIR* pDir
);
Description
This funciton wraps readdir(3B).
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.
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.
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.
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.
Perform sigprocmask
Syntax
int Ns_Sigmask (
int how,
sigset_t* set,
sigset_t* oset
);
Description
This function wraps sigprocmask(2).
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).
Perform sigwait
Syntax
int Ns_Sigwait (
sigset_t* set,
int* sig
);
Description
This function wraps sigwait(3).
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.
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;
}
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;
}
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.
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.