#Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_RegisterShutdown Overview Register a shutdown procedure. Syntax typedef void (Ns_Callback) (void *context); Ns_ProcHandle Ns_RegisterShutdown( Ns_Callback *proc, void *context ); Description The Ns_RegisterShutdown function registers proc as a shutdown procedure. The server calls all shutdown procedures before shutting down, in last-registered first-run order. The shutdown procedure takes the context as its sole argument. A shutdown procedure is often used to close or free a resource allocated by a module's initialization routine. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_RelativeUrl Overview Get relative filename portion of URL Syntax char *Ns_RelativeUrl( char *url, char *location ); Description Given a URL and a location, Ns_RelativeUrl returns a pointer to the relative filename portion of the specified URL. The example below returns a pointer to /index.html. Examples /* returns a pointer to /index.html */ Ns_RelativeUrl("http://www.foo.com/index.html", "http://www.foo.com"); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ReleaseSemaphore Overview Increment the semaphore count Syntax int Ns_ReleaseSemaphore( Ns_Semaphore * sema, int count ); Description Increment the semaphore count. Ns_SemaPost is the preferred function for incrementing the semaphore count. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_RollFile Overview 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. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_RWLockDestroy Overview Destroy a read/write lock Syntax void Ns_RWLockDestroy ( Ns_RWLock* ); Description Ns_RWLockDestroy frees the read/write lock's associated resources. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_RWLockInit Overview Initialize a read/write lock Syntax void Ns_RWLockInit ( Ns_RWLock* ); Description Initialize a read/write lock for use. A lock ID is returned via the lock parameter, which can be used in the other read/write lock functions. About Read/Write Locks Read/write locks are a serialization mechanism for using data structures where multiple reads can happen simultaneously, but where writes must happen singly. For example, suppose you have a hash table that is heavily used but doesn't change very often. You'd like to have multiple threads be able to read from the table without blocking on each other, but when you need to update the table, you can do so safely without having to worry about other threads reading incorrect data. The principal feature of read/write locks is the mechanism of which locks have priority and which locks must wait. Any number of read locks can be pending. If there's a write lock active, the read lock acquisition blocks until the write lock is released. Also, only one write lock can be in effect. If there are pending read locks active, the write lock acquisition blocks until all of the read locks drain. If a subsequent read lock acquisition attempt is made while a write lock is waiting to acquire, the write lock has priority. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_RWLockRdLock Overview Acquire a read lock Syntax void Ns_RWLockRdLock ( Ns_RWLock *lockPtr ); Description Ns_RWLockRdLock acquires a read lock. Any number of read locks can be pending. If there's a write lock active, the read lock acquisition blocks until the write lock is released. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_RWLockUnlock Overview Release a read/write lock Syntax void Ns_RWLockUnlock ( Ns_RWLock *lockPtr ); Description Ns_RWLockUnlock releases a read or write lock. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_RWLockWrLock Overview Acquire a write lock Syntax void Ns_RWLockWrLock ( Ns_RWLock *lockPtr ); Description Ns_RWLockWrLock acquires a write lock. Only one write lock can be in effect. If there are pending read locks active, the write lock acquisition blocks until all of the read locks drain. If a subsequent read lock acquisition attempt is made, the write lock has priority. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ScheduleDaily Overview Schedule a procedure to run once a day Syntax int Ns_ScheduleDaily( Ns_SchedProc *proc, void *context, int flags, int hour, int minute, Ns_SchedProc *cleanup ); Description The Ns_ScheduleDaily function schedules the procedure (proc) to be run once a day at the specified time (hour and minute). The proc is the scheduled procedure that will be run once a day. It is a function that takes the context and id of the schedule procedure. The id can be used in the Ns_UnscheduleProc procedure to stop the procedure from being called again. typedef void (Ns_SchedProc) (void *context, int id); The context is the context to pass to the scheduled procedure. The possible flags are NS_SCHED_ONCE and NS_SCHED_THREAD. If you specify NS_SCHED_ONCE, the procedure will only be executed once on the specified day and time, and it will not be re-scheduled to execute again the next day. By default, the procedure is re-scheduled after every time it is executed. If you specify NS_SCHED_THREAD, the procedure will run detached in a separate thread instead of using the one scheduled procedure thread used by all other scheduled procedures. You should use NS_SCHED_THREAD if the procedure will not return immediately. Note that if you use NS_SCHED_THREAD, and the procedure is still active the next time to run occurs, the next run is skipped instead of just delayed. The hour can be an integer from 0 to 23, and the minute an integer from 0 to 59. The cleanup procedure will be run once when the proc procedure is unscheduled. Examples Run a procedure (MyProc) once in its own thread at 2:30 a.m.: Ns_ScheduleDaily(myProc, myCtx, NS_SCHED_ONCE | NS_SCHED_THREAD, 2, 30, NULL) [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ScheduleProc Overview Schedule a procedure to run at specified intervals Syntax int Ns_ScheduleProc( void (*proc) (), void *context, int fNewThread, int interval ); Description The Ns_ScheduleProc function schedules the procedure proc to be run every interval seconds, with context as an argument. The flag fNewThread determines whether proc runs in its own thread. Ns_ScheduleProc returns an integer id for use in the Ns_UnscheduleProc function. Note that the newer Ns_ScheduleProcEx function provides a superset of the functionality in Ns_ScheduleProc. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ScheduleProcEx Overview Schedule a procedure to run at specified intervals Syntax int Ns_ScheduleProcEx( Ns_SchedProc *proc, void *context, int flags, int interval, Ns_SchedProc *cleanup ); Description The Ns_ScheduleProcEx function schedules the procedure (proc) to be run at a specific time interval specified in seconds. Ns_ScheduleProcEx returns an integer id for use in the Ns_UnscheduleProc function. The proc procedure is the scheduled procedure that will be run at each interval. It is a function that takes the context and id of the schedule procedure. The id can be used in the Ns_UnscheduleProc procedure to stop the procedure from being called again. typedef void (Ns_SchedProc) (void *context, int id); The context is the context to pass to the scheduled procedure. The possible flags are NS_SCHED_ONCE and NS_SCHED_THREAD. If you specify NS_SCHED_ONCE, the procedure will only be executed once on the specified day and time, and it will not be re-scheduled to execute again. By default, the procedure is re-scheduled after every time it is executed. If you specify NS_SCHED_THREAD, the procedure will run detached in a separate thread instead of using the one scheduled procedure thread used by all other scheduled procedures. You should use NS_SCHED_THREAD if the procedure will not return immediately. Note that if you use NS_SCHED_THREAD, and the procedure is still active the next time to run occurs, the next run is skipped instead of just delayed. The interval is the number of seconds between runs of the procedure. The cleanup procedure will be run once when the proc procedure is unscheduled. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ScheduleWeekly Overview Schedule a procedure to run once a week Syntax int Ns_ScheduleWeekly( Ns_SchedProc *proc, void *context, int flags, int day, int hour, int minute, Ns_SchedProc *cleanup ); Description The Ns_ScheduleWeekly function schedules the procedure (proc) to be run once a week on the specified day (day) at the specified time (hour and minute). The proc procedure is the scheduled procedure that will be run once a week. It is a function that takes the context and id of the schedule procedure. The id can be used in the Ns_UnscheduleProc procedure to stop the procedure from being called again. typedef void (Ns_SchedProc) (void *context, int id); The context is the context to pass to the scheduled procedure. The possible flags are NS_SCHED_ONCE and NS_SCHED_THREAD. If you specify NS_SCHED_ONCE, the procedure will only be executed once on the specified day and time, and it will not be re-scheduled to execute again the next week. By default, the procedure is re-scheduled after every time it is executed. If you specify NS_SCHED_THREAD, the procedure will run detached in a separate thread instead of using the one scheduled procedure thread used by all other scheduled procedures. You should use NS_SCHED_THREAD if the procedure will not return immediately. Note that if you use NS_SCHED_THREAD, and the procedure is still active the next time to run occurs, the next run is skipped instead of just delayed. The day can be an integer from 0 to 6, where 0 represents Sunday. The hour can be an integer from 0 to 23, and the minute an integer from 0 to 59. The cleanup procedure will be run once when the proc procedure is unscheduled. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SemaDestroy Overview Destroy a semaphore object Syntax int Ns_SemaDestroy( Ns_Sema* ); Description Free the resources associated with the semaphore. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SemaInit Overview Initialize a semaphore Syntax int Ns_SemaInit( Ns_Sema* , int count ); Description Initialize the semaphore with a semaphore count of count. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SemaPost Overview Increment the semaphore count Syntax int Ns_SemaPost( Ns_Sema* , int count ); Description Increment the semaphore count. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SemaWait Overview Wait for a semaphore count to be greater than zero. Syntax int Ns_SemaWait( Ns_Sema* ); Description If the semaphore count is greater than zero, decrement it and continue. Otherwise, block until this is possible. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ServerSpecificAlloc Overview Return unique integer to use in other functions Syntax int Ns_ServerSpecificAlloc(void); Description The Ns_ServerSpecificAlloc function returns a unique integer to be used in the Ns_ServerSpecific* storage functions, below. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ServerSpecificDestroy Overview Delete server-specific data Syntax void *Ns_ServerSpecificDestroy( char *handle, int id, int flags ); Description The Ns_ServerSpecificDelete function deletes server-specific data previously stored with Ns_ServerSpecificSet. The flags argument can be NS_OP_NODELETE or NS_OP_RECURSE. NS_OP_NODELETE determines whether the deletefunc specified in Ns_ServerSpecificSet is called. NS_OP_RECURSE determines whether this operation is applied recursively. An id of -1 matches all ids. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ServerSpecificGet Overview Retrieve server-specific data Syntax void *Ns_ServerSpecificGet( char *handle, int id ); Description The Ns_ServerSpecificGet function retrieves server-specific data stored previously with the Ns_ServerSpecificSet function. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ServerSpecificSet Overview Store server-specific data for subsequent retrieval Syntax void Ns_ServerSpecificSet( char *handle, int id, void *data, int flags, void (*deletefunc) (void *) ); Description The Ns_ServerSpecificSet function stores server-specific data, allowing subsequent retrieval using handle and id. The flags argument can be NS_OP_NODELETE. The deletefunc function is called with data as an argument when this handle/id combination is re-registered or deleted, or when this server shuts down, unless NS_OP_NODELETE is set. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetCopy Overview Create a new copy of a set Syntax Ns_Set *Ns_SetCopy( Ns_Set *old ); Description This function returns a newly allocated set that contains the same fields as the original set. The two sets share no memory and can be freed individually. Examples Ns_Set *setA; Ns_Set *setB; setA = Ns_SetCreate("setA"); Ns_SetPut(setA, "foo", "foovalue"); setB = Ns_SetCopy(setA); Ns_SetFree(setA); /* do something with setB */ Ns_SetFree(setB); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetCreate Overview Create a new Ns_Set Syntax Ns_Set *Ns_SetCreate( char *name ); Description The Ns_SetCreate function allocates and returns a pointer to a new Ns_Set. You must eventually call Ns_SetFree to release the memory used by the set. Examples Ns_Set *aSet; aSet = Ns_SetCreate(""); /* set name can be NULL */ Ns_SetPut(aSet, "foo", "foovalue"); /* do something with aSet */ Ns_SetFree(aSet); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetDelete Overview Remove a field from a set by field index Syntax void Ns_SetDelete( Ns_Set *set, int index ); Description The Ns_SetDelete function removes the field of the given index from the set. Any fields that follow the deleted field are moved up to keep the set contiguous. Examples Ns_Set *aSet; aSet = Ns_SetCreate(""); Ns_SetPut(aSet, "foo", "foovalue"); Ns_SetPut(aSet, "bar", "barvalue"); Ns_SetDelete(aSet, 0); /* deletes foo->foovalue */ /* finish processing of aSet */ Ns_SetFree(aSet); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetDeleteKey Overview Remove a field from a set by key name Syntax void Ns_SetDeleteKey( Ns_Set *set, char *key ); Description The Ns_SetDeleteKey function removes the field whose key name matches the given key. Any fields that follow the deleted field are moved up to keep the set contiguous. If more than one field in the set has the same key name, Ns_Set-DeleteKey deletes just the first field. The Ns_SetIDeleteKey function is this function's case-insensitive counterpart. Examples Ns_Set *aSet; aSet = Ns_SetCreate(""); Ns_SetPut(aSet, "foo", "foovalue"); Ns_SetPut(aSet, "bar", "barvalue"); Ns_SetDeleteKey(aSet, "foo"); /* deletes foo->foovalue */ /* finish processing of aSet */ Ns_SetFree(aSet); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetDriverProc Overview Set socket driver callback Syntax int Ns_SetDriverProc ( Ns_Driver driver, Ns_DrvId id, void* proc ); Description Set a single socket driver callback procedure. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetEvent Overview Wake up one waiting event Syntax int Ns_SetEvent( Ns_Event * event ); Description Wake up one waiter, if there are any waiters to be awakened. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetFind Overview Locate the index of a field within an Ns_Set Syntax int Ns_SetFind( Ns_Set *set, char *key ); Description The Ns_SetFind function returns the index of the first field whose key name matches the given key. The index is in C array order, i.e., 0 is the index of the first field. If no fields are found, Ns_SetFind returns -1. If more than one field in the set has the same key name, Ns_SetFind returns just the first field index. The Ns_SetIFind function is this function's case-insensitive counterpart. Examples Ns_Set *aSet; int index; aSet = Ns_SetCreate(""); Ns_SetPut(aSet, "Foo", "foovalue"); Ns_SetPut(aSet, "Bar", "barvalue"); index = Ns_SetFind(aSet, "Foo"); /* case sensitive search*/ if (index == -1) { Ns_Log(Warning, "set key Foo not found"); } else { Ns_Log(Notice, "Value for Foo is %s", Ns_SetGet(aSet, "Foo")); } Ns_SetFree(aSet); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetFree Overview Free memory used by an Ns_Set Syntax void Ns_SetFree( Ns_Set *set ); Description The Ns_SetFree function deletes all the fields of an Ns_Set and frees the set structure. After calling Ns_SetFree, the set is no longer valid and cannot be used. Examples Ns_Set *aSet; aSet = Ns_SetCreate(""); /* set name can be NULL */ Ns_SetPut(aSet, "foo", "foovalue"); /* do something with aSet */ Ns_SetFree(aSet); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetGet Overview Return the value for a field Syntax char *Ns_SetGet( Ns_Set *set, char *key ); Description The Ns_SetGet function returns the value of the first field whose key name matches the given key. Ns_SetGet returns NULL if no field is found. If more than one field in the set has the same key name, Ns_SetGet returns just the first field. The Ns_SetIGet function is this function's case-insensitive counterpart. Examples Ns_Set *aSet; int index; aSet = Ns_SetCreate(""); Ns_SetPut(aSet, "Foo", "foovalue"); Ns_SetPut(aSet, "Bar", "barvalue"); Ns_Log(Notice, "Value for Foo is %s", Ns_SetGet(aSet, "Foo")); Ns_SetFree(aSet); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetIDeleteKey Overview Remove a field from a set by key name case-insentively Syntax void Ns_SetIDeleteKey( Ns_Set *set, char *key ); Description The Ns_SetIDeleteKey function is the case-insensitive counterpart to the Ns_SetDeleteKey function. It removes the field whose key name matches the given key case-insensitively. Any fields that follow the deleted field are moved up to keep the set contiguous. If more than one field in the set has the same key name, Ns_Set-IDeleteKey deletes just the first field. Examples Ns_Set *aSet; aSet = Ns_SetCreate(""); Ns_SetPut(aSet, "foo", "foovalue"); Ns_SetPut(aSet, "bar", "barvalue"); Ns_SetIDeleteKey(aSet, "Foo"); /* deletes foo->foovalue */ /* finish processing of aSet */ Ns_SetFree(aSet); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetIFind Overview Locate the index of a field case-insensitively Syntax int Ns_SetIFind( Ns_Set *set, char *key ); Description The Ns_SetIFind function is the case-insensitive counterpart of the Ns_SetFind function. It returns the index of the first field whose key name matches the given key case-insensitively. The index is in C array order, i.e., 0 is the index of the first field. If no fields are found, Ns_SetIFind returns -1. If more than one field in the set has the same key name, Ns_SetIFind returns just the first field index. Examples Ns_Set *aSet; int index; aSet = Ns_SetCreate(""); Ns_SetPut(aSet, "Foo", "foovalue"); Ns_SetPut(aSet, "Bar", "barvalue"); index = Ns_SetIFind(aSet, "foo"); /* case insensitive search*/ if (index == -1) { Ns_Log(Warning, "set key foo not found"); } else { Ns_Log(Notice, "Value for Foo is %s", Ns_SetGet(aSet, "ooo")); } Ns_SetFree(aSet); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetIGet Overview Return the value for a field case-insensitively Syntax char *Ns_SetIGet( Ns_Set *set, char *key ); Description The Ns_SetIGet function is the case-insensitive counterpart to the Ns_SetGet function. It returns the value of the first field whose key name matches the given key case-insensitively. Ns_SetIGet returns NULL if no field is found. If more than one field in the set has the same key name, Ns_SetIGet returns just the first field. Examples Ns_Set *aSet; int index; aSet = Ns_SetCreate(""); Ns_SetPut(aSet, "Foo", "foovalue"); Ns_SetPut(aSet, "Bar", "barvalue"); Ns_Log(Notice, "Value for foo is %s", Ns_SetIGet(aSet, "foo")); Ns_SetFree(aSet); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetIUnique Overview Check if a key in an Ns_Set is unique (case insensitive) Syntax int Ns_SetIUnique( Ns_Set *set, char *key ); Description Ns_SetIUnique returns 1 if the specified key is unique in the specified set and 0 if it is not. The test for uniqueness is performed case-insensitively. The case-sensitive counterpart to this function is Ns_SetUnique. For example, a client could send multiple "Accept:" headers which would end up in the header set for the connection. Ns_SetIUnique would then return 0 for the header set and the "Accept" key, because there are multiple fields with the key "Accept". [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetKey Overview Return the key name of a field Syntax char *Ns_SetKey( Ns_Set *set, int index ); Description The Ns_SetKey macro returns the field key name of the field at the given index. Examples Ns_Set *aSet; aSet = Ns_SetCreate(""); Ns_SetPut(aSet, "foo", "foovalue"); Ns_SetPut(aSet, "bar", "barvalue"); printf("Key at index 0 is %s\n", Ns_SetKey(aSet, 0)); /* finish processing of aSet */ Ns_SetFree(aSet); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetLast Overview Return the index of the last element of a set Syntax void Ns_SetLast( Ns_Set *set ); Description The Ns_SetLast function returns the index of the last element of the set. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetListFind Overview Locate a set by name in a set list Syntax Ns_Set *Ns_SetListFind( Ns_Set **sets, char *name ); Description The Ns_SetListFind function returns the set of the given name in NULL-terminated array of sets most likely generated by the Ns_SetSplit function. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetListFree Overview Free a list of sets Syntax void Ns_SetListFree( Ns_Set **sets ); Description The Ns_SetListFree function frees the sets in a NULL-terminated array of sets and then frees the array itself. This function is normally used to free a list of sets generated by Ns_SetSplit. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetMerge Overview Merge two sets Syntax void Ns_SetMerge( Ns_Set *high, Ns_Set *low ); Description The Ns_SetMerge function appends any fields from the low set to the high set if a field with the name key name does not already exist in the high set. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetMove Overview Move fields from one set to the end of another Syntax void Ns_SetMove( Ns_Set *to, Ns_Set *from ); Description The Ns_SetMove function moves all fields from the from set to the end of the to set. Ns_SetMove leaves from as a valid empty set. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetName Overview Return the name of a set Syntax char *Ns_SetName( Ns_Set *set ); Description The Ns_SetName function returns the name of the set, which may be NULL. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetPrint Overview Print the contents of a set to the AOLserver error log Syntax void Ns_SetPrint( Ns_Set *set ); Description The Ns_SetPrint function prints all fields in a set to the AOLserver error log file (or the terminal if the AOLserver is running in foreground mode). It is useful for debugging. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetPut Overview Add a field to an Ns_Set Syntax int Ns_SetPut( Ns_Set *set, char *key, char *value ); Description The Ns_SetPut function adds a new field to a set whose key name is the given key and value is the given value. The value of the new field may be NULL. The index of the new field is returned. Ns_SetPut strcpy's the value and uses realloc's to adjust the size of the fields to accommodate. Examples Ns_Set *aSet; aSet = Ns_SetCreate(""); Ns_SetPut(aSet, "foo", "foovalue"); Ns_SetPut(aSet, "bar", "barvalue"); /* finish processing of aSet */ Ns_SetFree(aSet); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetPutValue Overview Set the value of a field Syntax void Ns_SetPutValue( Ns_Set *set, int index, char *value ); Description The Ns_SetPutValue function sets the value of the field at the given index to the new value. Any existing value of the affected field overwritten. If the specified index is greater than the number of fields in the set, this function does nothing. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetRequestAuthorizeProc Overview Set function used by Ns_AuthorizeRequest Syntax typedef int (Ns_RequestAuthorizeProc) ( char *hServer, char *method, char *url, char *authuser, char *authpasswd, char *peeraddr ); void Ns_SetRequestAuthorizeProc( char *hServer, Ns_RequestAuthorizeProc *proc ); Description The Ns_SetRequestAuthorizeProc can be used to set the procedure used by Ns_AuthorizeRequest to authenticate users accessing URLs on your system. The authentication procedure must match the Ns_RequestAuthorizeProc prototype and return one of the values listed in the description of Ns_AuthorizeRequest above. The AOLserver permissions module calls Ns_SetRequestAuthorizeProc at startup to register its file-based permission system. If your site already has a permission system in place, you could write a C module whose initialization function opens a connected to the existing system and then calls Ns_SetRequestAuthorizeProc to override the permission module's authentication system. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetRequestUrl Overview Fill in request structure Syntax void Ns_SetRequestUrl ( Ns_Request* request, char* url ); Description Fill in a request structure. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetSize Overview Return the current size of a set Syntax int Ns_SetSize( Ns_Set *set ); Description The Ns_SetSize macro returns the current number of fields in a set. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetSplit Overview Split a set into an array of new sets Syntax Ns_Set **Ns_SetSplit( Ns_Set *set, char sep ); Description The Ns_SetSplit function assumes that each key name in the fields of a set contains a separating character. The fields of the set are partitioned into new sets whose set names are the characters before the separator and whose field key names are the characters after the separator. For example, if the separator is `.' and the set has fields whose key names are the following: dog.sound dog.food cat.sound cat.food Ns_SetSplit would create two new sets named dog and cat, each containing two fields whose key names are sound and food. Ns_SetSplit returns a newly allocated NULL-terminated array of new sets. The original set is left unaltered. The list of new sets can be freed at once with the Ns_SetListFree function. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetThreadLocalStorage Overview Set thread local storage Syntax int Ns_SetThreadLocalStorage( Ns_ThreadLocalStorage * tls, void *p ); Description Set the thread local storage tls to the value p. Examples See the example for Ns_AllocThreadLocalStorage. Ns_TlsSet is the preferred function for setting thread local storage. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetTrunc Overview Truncate an Ns_Set Syntax void Ns_SetTrunc( Ns_Set *set, int size ); Description The Ns_SetTrunc function reduces the set to the first size key-value pairs and frees the memory for the rest of the key-value pairs that may have been in the set. Examples /* Eliminate the headers sent by a browser. */ Ns_SetTrunc(conn->headers, 0); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetUnique Overview Check if a key in an Ns_Set is unique (case sensitive) Syntax int Ns_SetUnique( Ns_Set *set, char *key ); Description Ns_SetUnique returns 1 if the specified key is unique in the specified set and 0 if it is not. The test for uniqueness is performed case-sensitively. The case-insensitive counterpart to this function is Ns_SetIUnique. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetUpdate Overview Update an Ns_Set value Syntax void Ns_SetUpdate ( Ns_Set* set, char* key, char* value ); Description Remove an item from the Ns_Set whose key = key, if one exists, and then re-add the item with the new value. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetUrlToFileProc Overview 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. See also Ns_UrlToFile() Ns_MakePath() [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetUserAuthorizeProc Overview 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. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SetValue Overview Return the value of a field Syntax char *Ns_SetValue( Ns_Set *set, int index ); Description The Ns_SetValue macro returns the value of the field at the given index. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_Sigmask Overview Perform sigprocmask Syntax int Ns_Sigmask ( int how, sigset_t* set, sigset_t* oset ); Description This function wraps sigprocmask(2). [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_Signal Overview 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). [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_Sigwait Overview Perform sigwait Syntax int Ns_Sigwait ( sigset_t* set, int* sig ); Description This function wraps sigwait(3). [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SkipUrl Overview Skip past path elements in the URL of a request Syntax char *Ns_SkipUrl( Ns_Request *request, int nurl ); Description The Ns_SkipUrl function returns the request URL after skipping past the first nurl elements. Examples /* PathInfo - Request to return URL after the first 2 parts. */ int PathInfo(Ns_Conn *conn, void *ctx) { char *info; /* Skip past the first two parts */ info = Ns_SkipUrl(conn->request, 2); return Ns_ConnReturnNotice(conn, 200, info, NULL); } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SockAsyncConnect Overview Create a remote socket and return immediately Syntax SOCKET Ns_SockAsyncConnect ( char *host, int port ); Description Ns_SockAsyncConnect creates a socket connected to a remote host and port, returning immediately with the connection in progress. A select call can later be used to determine when the connection has been established. Examples SOCKET sock; fd_set set; struct timeval tv; sock = Ns_SockAsyncConnect("mailhost", 25); ... perform some other work while connection is in progress... ... check for connection ... tv.tv_sec = 2; /* allow 2 more seconds */ tv.tv_usec = 0; FD_ZERO(&set); FD_SET(sock, &set); if (select(sock+1, NULL, &set, NULL, &tv) != 1) { ... timeout - close socket and return error... Ns_CloseLater(sock); } else { ... use socket ... } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SockCallback Overview Register a socket callback function Syntax int Ns_SockCallback ( SOCKET sock, Ns_SockProc *proc, void *ctx, int when ); Description Ns_SockCallback registers a user-defined socket callback function and should be called by your module at startup time. You must create a listening TCP socket (named sock). The ctx argument is your context which will be passed back as the second argument of your callback function. The when argument is a bitmask with one or more of the following options specified: NS_SOCK_READ: the socket is readable NS_SOCK_WRITE: the socket is writeable NS_SOCK_EXCEPTION: the socket has an exceptional condition NS_SOCK_EXIT: the server is shutting down The proc is your socket callback function in the following format: typedef int (Ns_SockProc) (int sock, void *arg, int why); The sock will be a readable, writable socket. The arg is the ctx you passed to Ns_SockCallback. The why argument is the when you passed to Ns_SockCallback. At startup time, AOLserver creates a single socket service thread dedicated to handling socket callbacks. Since several sockets are needed to listen for connection requests, and because connection requests are handled so quickly, all the socket drivers share a single thread for that purpose. Examples 1. Create a C callback function to handle a request. The callback function must execute without blocking so that other sockets can get serviced. Typically, the callback function just performs an accept() call and queues the request. The prototype is: typedef int (Ns_SockProc) (SOCKET sock, void *context, int why); The parameters are: sock the registered socket context your context passed to Ns_SockCallback() why the reason the function was called, which is one of the following: NS_SOCK_READ: the socket is readable NS_SOCK_WRITE: the socket is writeable NS_SOCK_EXCEPTION: the socket has an exceptional condition NS_SOCK_EXIT: the server is shutting down The callback function must return either NS_TRUE to tell the socket thread to keep watching the socket or NS_FALSE to tell the socket thread to stop watching the socket. For example: int MySock(SOCKET sock, void *context, int why) { if (why == NS_SOCK_READ) { .. handle read .. if (error) { return NS_FALSE; } else { return NS_TRUE; } } else if (why == NS_SOCK_EXIT) { .. free(context) .. return NS_FALSE; } } 2. At server startup time, your module must register your callback function with the server using the Ns_SockCallback() function. This example specifies that MySock will be called when the socket is readable or when the server is shutting down: Ns_SockCallback(sock, MySock, myCtx, NS_SOCK_READ | NS_SOCK_EXIT); Remember that there is only one socket service thread, so your callback function must return immediately without blocking! [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SockCancelCallback Overview Remove a socket callback Syntax void Ns_SockCancelCallback( int sock ); Description Remove a callback registered on a socket. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SockConnect Overview Create a socket to a remote host and port Syntax SOCKET Ns_SockConnect ( char *host, int port ); Description Ns_SockConnect creates a socket connected to a remote host and port. Ns_SockConnect waits for the connection to be established before returning. Examples sock = Ns_SockConnect("mailhost", 25); if (sock != INVALID_SOCKET) { ... talk SMTP over sock ... } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SockListen Overview Create a socket on a specified address and port Syntax SOCKET Ns_SockListen ( char *host, int port ); Description Ns_SockListen creates a socket listening for connections on the specified address and port. Examples sock = Ns_SockListen("localhost", 25); while (1) { new = accept(sock, NULL, 0); ... communicate with client on new ... } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SockListenCallback Overview Register a socket callback function and create socket Syntax int Ns_SockListenCallback ( char* address, int port, Ns_SockProc* proc, void* ctx ); Description Ns_SockListenCallback registers a user-defined socket callback function and should be called by your module at startup time. It also creates, binds, and listens on the socket (with the specified address and port) for you. The proc is your socket callback function. The ctx argument is your context which will be passed back as the second argument of your callback function. The when argument is a bitmask with one or more of the following options specified: NS_SOCK_READ: the socket is readable NS_SOCK_EXIT: the server is shutting down [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SockPipe Overview Return a pair of connected sockets Syntax int Ns_SockPipe ( SOCKET socks[2] ); Description Ns_SockPipe returns a pair of connected sockets. On Unix, Ns_SockPipe uses socketpair(). A socket pipe can be used for IPC between threads or as a way to wakeup a thread waiting in a select call as in the example below. Examples SOCKET sockPipe[2]; /* Init - called at startup to create the pipe. */ void Init(void) { Ns_SockPipe(sockPipe); } /* Wakeup - called by another thread to stop InteruptableIO in another thread. */ void Wakeup(void) { send(sockPipe[1], "w", 1, 0); } /* InterruptableIO - called by a thread dedicated to reading from a remote host. Reading will continue until another thread calls Wakeup, causing sockPipe to be readable. */ void InteruptableIO(void) { SOCKET sock, max; fd_set set; char sig; sock = Ns_SockConnect("slowmachine", 6767); FD_ZERO(&set); FD_SET(sock, &set); FD_SET(sockPipe[0], &set); max = sockPipe; if (sock > max) { max = sock; } while (1) { select(max+1, &set, NULL, NULL, NULL); if (FD_ISSET(sockPipe[0], &set)) { /* Another thread called Wakeup(). * Read the signal and return. */ recv(sockPipe[0], &sig, 1, 0); closesocket(sock); return; } else if (FD_ISSET(sock, &set)) { recv(sock, buf, sizeof(buf), 0); ... process buf ... } } } Note: Interruptable I/O typically makes use of the alarm() system call on Unix. The method above, used throughout AOLserver, works on all platforms and avoids the alarm system call which is inappropriate for a multithreaded application. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SockPortBound Overview Determine if port is bound Syntax int Ns_SockPortBound ( int port ); Description This function returns a boolean value specifying whether the specified port is already bound. The port is a TCP port, and INADDR_ANY is assumed. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SockSetBlocking Overview Set a socket in blocking mode Syntax Ns_SockSetBlocking ( SOCKET sock ); Description Ns_SockSetBlocking sets a socket in blocking I/O mode. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SockSetNonBlocking Overview Set a socket in nonblocking mode Syntax Ns_SockSetNonBlocking ( SOCKET sock ); Description Ns_SockSetNonBlocking sets a socket in nonblocking I/O mode. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_SockTimedConnect Overview Create a remote socket within a specified time Syntax SOCKET Ns_SockTimedConnect ( char *host, int port, int timeout ); Description Ns_SockTimedConnect creates a socket connected to a remote host and port, ensuring that the connection is established within the number of seconds specified by the timeout argument. Examples sock = Ns_SockTimedConnect("mailhost", 25); if (sock == INVALID_SOCKET) { ... timeout or error connecting ... } else { ... use socket ... } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_StrCaseFind Overview Perform strstr Syntax char* Ns_StrCaseFind ( char* string, char* substr ); Description This function performs a case-insensitive strstr(3C). [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_StrCopy Overview Copy a string or NULL value using Ns_Malloc Syntax char *Ns_StrCopy( char *string ); Description The Ns_StrCopy function is identical to the Ns_StrDup function but allows for the string parameter to be NULL, in which case Ns_StrCopy does nothing and returns NULL. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_StrDup Overview Copy a string using Ns_Malloc Syntax char *Ns_StrDup( char *string ); Description The Ns_StrDup function calls Ns_Malloc to allocate enough memory to make a copy of the given string. This function replaces the system strdup function. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_StringPrint Overview Print string Syntax void Ns_StringPrint ( char* s ); Description This function prints the specified string to stdout. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_Strtok Overview Perform strtok_r Syntax char* Ns_Strtok ( char* s1, const char* s2 ); Description This function wraps strtok_r(3C). [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_StrToLower Overview Lowercase string Syntax char* Ns_StrToLower ( char* string ); Description This function converts the specified string to lowercase. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_StrToUpper Overview Uppercase string Syntax char* Ns_StrToUpper ( char* string ); Description This function converts the specified string to uppercase. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_StrTrim Overview Trim string Syntax char* Ns_StrTrim ( char* string ); Description This function trims all blanks from the specified string. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_StrTrimLeft Overview Trim blanks from left Syntax char* Ns_StrTrimLeft ( char* string ); Description This function trims all blanks from the left of the string. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_StrTrimRight Overview Trim blanks from right Syntax char* Ns_StrTrimRight ( char* string ); Description This function trims all blanks from the right of the string. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclAllocateInterp Overview Allocate an interpreter for a server Syntax Tcl_Interp *Ns_TclAllocateInterp( char *hServer ); Description This function reserves and returns a Tcl interpreter associated with the server. You will usually want to use the Ns_GetConnInterp function instead, since connections often already have interpreters associated with them. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclAppendInt Overview Append integer to Tcl result Syntax void Ns_TclAppendInt ( Tcl_Interp* interp, int value ); Description Append an integer to the Tcl result. This is essentially a safe version of sprintf(interp->result, "%d", value). [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclDeAllocateInterp Overview Perform cleanup after deallocating a Tcl interpreter Syntax int Ns_TclDeAllocateInterp( Tcl_Interp *interp ); Description This function is called automatically after each Tcl request procedure if the AutoClose configuratin parameter is set on. Sets created by Ns_TclEnterSet are deleted or not deleted, depending on the flags set in the Ns_TclEnterSet function. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclDestroyInterp Overview Mark Tcl interpreter for deletion Syntax void Ns_TclDestroyInterp ( Tcl_Interp* ); Description Mark the Tcl interpreter for deletion. At thread death, clean up its state, close files, free memory, etc. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclEnterSet Overview Make an Ns_Set accessible through Tcl Syntax int Ns_TclEnterSet( Tcl_Interp *interp, Ns_Set *set, int flags ); Description Ns_TclEnterSet makes an Ns_Set accessible through Tcl. The new set ID is sprintf'ed directly into interp->result. It returns either NS_OK or NS_ERROR. The flags can be one or more of the following: NS_TCL_SET_TEMPORARY: The set is temporary and private to the Tcl interpreter. The set ID will be automatically deleted by Ns_TclDeAllocateInterp(). NS_TCL_SET_PERSISTENT: The set can be accessed by any Tcl interpreter in the server and the set ID will persist beyond the interpreter's next call to Ns_TclDeAllocateInterp(). NS_TCL_SET_DYNAMIC: The set was dynamically allocated for use by Tcl and will be garbage-collected when the cooresponding set ID is deleted through either Ns_TclFreeSet() or Ns_TclDeAllocateInterp(). Sets created by Tcl are normally DYNAMIC and TEMPORARY unless the -persist option is used in the Tcl function when creating the set. Examples set = Ns_SetCreate(name); return Ns_TclEnterSet(interp, set, NS_TCL_SET_TEMPORARY | NS_TCL_SET_DYNAMIC); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclEval Overview Execute a Tcl script Syntax int Ns_TclEval ( Ns_DString *pds, char *hServer char *script ); Description The Ns_TclEval function executes the Tcl function specified by script on the server specified by hServer. It writes the results to the passed-in pds variable. Note that the string in script may be temporarily modified by Tcl, so it must be writable. For example, use: char script[*]="sometcl"; instead of: char *script="sometcl"; Examples Use this code to call ns_sendmail from C: NS_DStringVarAppend(&dsScript, "ns_sendmail", to, " ", from, " ", subject, " ", body); status=Ns_TclEval(&dsResult, Ns_ConnServer(conn), dsScript.string) [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclFreeSet Overview Free an Ns_Set Syntax int Ns_TclFreeSet( Tcl_Interp *interp, char *setId ); Description Ns_TclFreeSet frees the set specified by the set ID for the interpreter. If the set was initially entered with the NS_TCL_SET_DYNAMIC flag with Ns_TclEnterSet, the actual Ns_Set is also freed. Otherwise, the actual Ns_Set is not freed and the programmer is responsible for eventually freeing it. The ns_set free Tcl function calls this function. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclGetConn Overview Get connection Syntax Ns_Conn* Ns_TclGetConn ( Tcl_Interp* interp ); Description Return the conn associated with this thread. The interp parameter is ignored and should be NULL. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclGetOpenChannel Overview Get open channel in interpreter Syntax int Ns_TclGetOpenChannel ( Tcl_Interp* , char* chanId, int write, int check, Tcl_Channel* channPtr ); Description This function fills in channptr with a channel open in the passed-in interpreter if one exists. It returns TCL_OK or TCL_ERROR. The chanId is a channel name (the handle that Tcl uses). This function also has the ability to check if a channel is opened for reading or writing. If check is true, the check is performed. If write is true, the channel is checked for writeability. If write is false, the channel is checked for readability. If the check is performed and fails, then an error is returned and appended to the interpreter. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclGetOpenFd Overview Get open file descriptor Syntax int Ns_TclGetOpenFd ( Tcl_Interp* , char* chanId, int write, int* fdPtr ); Description This function returns an open Unix file descriptor for the specified channel. The value at fdPtr is updated with a valid Unix file descriptor. The write parameter specifies if a writable (TRUE) or readable (FALSE) channel is being requested. See the Tcl 7.6 documentation for Tcl_GetChannelFile. This function returns TCL_ERROR or TCL_OK. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclGetSet Overview Return the Ns_Set for the specified set ID Syntax Ns_Set *Ns_TclGetSet( Tcl_Interp *interp, char *setId ); Description Ns_TclGetSet returns the Ns_Set for the specified set ID. It returns NULL if the set ID is invalid or if there is no such set ID. The Ns_TclGetSet2 function does essentially the same thing, except the Ns_Set is stored in a pointer. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclGetSet2 Overview Return the Ns_Set for the specified set ID in a pointer Syntax int Ns_TclGetSet2( Tcl_Interp *interp, char *setId, Ns_Set **setPtr ); Description Ns_TclGetSet2 returns the Ns_Set in setPtr for the specified set ID. It returns TCL_OK if the set ID is valid and found. It returns TCL_ERROR if the set is invalid or can't be found. Examples if (Ns_TclGetSet2(interp, argv[1], &set) != TCL_OK { return TCL_ERROR; } You can then access the Ns_Set pointed to by set. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclInitInterps Overview Call a Tcl init procedure in the parent interpreter Syntax int Ns_TclInitInterps( char *hServer, Ns_TclInterpInitProc *proc, void *context ); Description Ns_TclInitInterps runs the specified procedure (proc) in the parent interpreter of the specified server. The definition of Ns_TclInterpInitProc is: typedef int (Ns_TclInterpInitProc) (Tcl_Interp *interp, void *context); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclInitModule Overview Source Tcl module before server startup Syntax int Ns_TclInitModule ( char* server, char* module ); Description Put this module on this list of modules whose Tcl is to be sourced before server startup and after modules are loaded. The server parameter is ignored. For example, calling Ns_TclInitModule(NULL, "nsfoo") from Ns_ModuleInit will cause the following directories to be sourced after all modules are loaded: (aolserver home)/servers/server1/modules/tcl/nsfoo/*.tcl (aolserver home)/modules/tcl/nsfoo/*.tcl [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclInterpServer Overview Return name of server Syntax char* Ns_TclInterpServer ( Tcl_Interp* interp ); Description Return the name of the server, such as "server1". The interp argument is ignored. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclLibrary Overview Return private Tcl directory Syntax char* Ns_TclLibrary (void); Description This function returns the name of the private Tcl directory, such as "(aolserver home)/servers/server1/modules/tcl". [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclLogError Overview Write errorInfo to log file Syntax char* Ns_TclLogError ( Tcl_Interp* interp ); Description This function writes the value of the errorInfo variable out to the log. See the Tcl documentation for more on the global errorInfo variable. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclMarkForDelete Overview Mark Tcl interpreter for deletion Syntax void Ns_TclMarkForDelete ( Tcl_Interp* ); Description Mark this interpreter for deletion. When the thread terminates (and it must be a connection thread), the tcl interpreter will be deleted. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclRegisterAtCreate Overview Register function for interpreter creation Syntax int Ns_TclRegisterAtCreate ( Ns_TclInterpInitProc* proc, void* arg ); Description Register a procedure to be called when an interpreter is first created for a thread. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TclRegisterDeferred Overview Register a function for interpreter cleanup Syntax void Ns_TclRegisterDeferred ( Tcl_Interp *interpPtr , Ns_TclDeferProc *deferProc , void *contex ); Description Register a procedure to be called when the interpreter is cleaned up. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ThreadCreate Overview Create new thread Syntax void Ns_ThreadCreate ( Ns_ThreadProc* proc, void* arg, long stackSize, Ns_Thread* threadPtr ); Description Create a new thread. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ThreadExit Overview Free or exit thread Syntax void Ns_ThreadExit ( int exitCode ); Description Cleanup the thread's tls and memory pool and either free the thread if it's detached or mark the thread as exited and allow it to be joined. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ThreadFree Overview Free thread pool memory Syntax void Ns_ThreadFree ( void* ptr ); Description Free previously allocated memory from the per-thread pool. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ThreadGetName Overview Get thread name Syntax char* Ns_ThreadGetName (void); Description Return a pointer to calling thread's string name, as set with Ns_ThreadSetName. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ThreadId Overview Get thread ID Syntax int Ns_ThreadId (void); Description Return the numeric thread id for the calling thread. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ThreadJoin Overview Wait for thread exit Syntax void Ns_ThreadJoin ( Ns_Thread* threadPtr, int* exitCodePtr ); Description Wait for exit of a non-detached thread. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ThreadMalloc Overview Allocate thread pool memory Syntax void* Ns_ThreadMalloc ( unsigned int size ); Description Allocate thread-pool memory. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ThreadPool Overview Get thread pool memory Syntax Ns_Pool* Ns_ThreadPool (void); Description Get this thread's memory pool. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ThreadRealloc Overview Realloc thread pool memory Syntax void* Ns_ThreadRealloc ( void* ptr, unsigned int size ); Description realloc for thread memory pools. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ThreadSelf Overview Get handle to thread Syntax void Ns_ThreadSelf ( Ns_Thread* threadPtr ); Description Return opaque handle to thread's data structure. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ThreadSetname Overview Set thread name Syntax void Ns_ThreadSetName ( char* name ); Description Set the name of the thread, which is used in the server.log. The name can be retrieved with Ns_ThreadGetName. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_ThreadYield Overview Yield processor time to runnable threads Syntax void Ns_ThreadYield(void); Description Ns_ThreadYield yields its processor time to any runnable threads with equal or higher priority. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TimedWaitForEvent Overview Wait for an event for a specified time Syntax int Ns_TimedWaitForEvent( Ns_Event * event, Ns_Mutex * lock, int usec ); Description Same as Ns_WaitForEvent except that it has a timeout in seconds. On timeout, the function returns NS_TIMEOUT. Examples Ns_LockMutex(&lock); if (!ready) { result = Ns_TimedWaitForEvent(&ev, &lock, 10); if (result == NS_TIMEOUT) { ... handle timeout ... } else if (result != NS_OK) { ... handle error ... } } Ns_UnlockMutex(&lock); [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TlsAlloc Overview Allocate thread local storage Syntax void Ns_TlsAlloc ( Ns_Tls* , Ns_TlsCleanup* ); Description Allocate thread-local-storage. This is unneeded if the tls variable is initialized to 0 (as static data is). See pthread_setspecific(3P) for details on thread-local storage. This function is a renamed version of Ns_AllocThreadLocalStorage. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TlsGet Overview Get thread local storage Syntax void* Ns_TlsGet ( Ns_Tls *tlsPtr ); Description Get thread-local-storage. This function is a renamed version of Ns_GetThreadLocalStorage. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_TlsSet Overview Set thread local storage Syntax void Ns_TlsSet ( Ns_Tls *tlsPtr , void *value ); Description Set thread local storage. This function is a renamed version of Ns_SetThreadLocalStorage. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_UnlockMutex Overview Unlock the mutual exclusion lock Syntax int Ns_UnlockMutex( Ns_Mutex * mutex ); Description Unlock the mutex. Ns_MutexLock is the preferred function for unlocking a mutex. Examples See the example for Ns_LockMutex. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_UnRegisterProxyRequest Overview Unregister a proxy request function Syntax void Ns_UnRegisterProxyRequest( char *Server, char *method, char *protocol ); Description The Ns_UnRegisterProxyRequest function unregisters the function for the specified method and protocol on a specific server. If the deleteProc is not null, it is called with the function's context as an argument. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_UnRegisterRequest Overview Unregister a function Syntax void Ns_UnRegisterRequest( char *hServer, char *method, char *URL, int flags ); Description The Ns_UnRegisterRequest function unregisters the function with the specified method/URL combination and with the same inheritance setting on a specific server. That is, if the flags argument is set to NS_OP_NOINHERIT in Ns_UnRegisterRequest, the function registered with the NS_OP_NOINHERIT flag in Ns_RegisterRequest (or the -noinherit flag in ns_register_proc) will be unregistered. If the flags argument is set to 0, the function registered without the NS_OP_NOINHERIT flag (or the -noinherit flag) will be unregistered. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_UnscheduleProc Overview Stop a scheduled procedure Syntax void Ns_UnscheduleProc ( int id ); Description The Ns_UnscheduleProc function stops a scheduled procedure from executing again. The scheduled procedure to be stopped is identified by its id, which was returned by the Ns_Schedule* function that was used to schedule the procedure. It is safe to call Ns_UnscheduleProc from inside a scheduled procedure. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_UrlIsDir Overview 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. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_UrlIsFile Overview 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; } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_UrlSpecificAlloc Overview Return unique integer to use in other functions Syntax int Ns_UrlSpecificAlloc(void); Description The Ns_UrlSpecificAlloc function returns a unique integer to be used in the Ns_UrlSpecific* storage functions below. Examples static int myId; void Init(void) { /* Allocate the id once at startup. */ myId = Ns_UrlSpecificAlloc(); } void Store(char *server, char *method, char *url, char *data) { Ns_UrlSpecificSet(server, method, url, myId, data, 0, NULL); } char * Fetch(char *server, char *method, char *url) { char *data; data = Ns_UrlSpecificGet(server, method, url, myId); return (char *) data; } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_UrlSpecificDestroy Overview Delete URL-specific data Syntax void *Ns_UrlSpecificDestroy( char *handle, char *method, char *url, int id, int flags ); Description The Ns_UrlSpecificDestroy function deletes URL-specific data previously stored with Ns_UrlSpecificSet with the same method/URL combination and the same inheritance setting. The flags argument can be NS_OP_NODELETE, NS_OP_RECURSE, or NS_OP_NOINHERIT. NS_OP_NODELETE determines whether the deletefunc specified in Ns_UrlSpecificSet is called. If NS_OP_RECURSE is set, then data for all URLs more specific than the passed-in URL is also destroyed. If the flags argument specifies NS_OP_NOINHERIT in Ns_UrlSpecificDestroy, the data stored with the NS_OP_NOINHERIT flag in Ns_UrlSpecificSet will be deleted. If the flags argument does not specify NS_OP_NOINHERIT, the data stored without the NS_OP_NOINHERIT flag will be deleted. An id of -1 matches all ids. For example, Ns_UrlSpecificDestroy("myserver", "GET", "/", -1, NS_OP_RECURSE) removes all data for the method GET for server "myserver". [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_UrlSpecificGet Overview Retrieve URL-specific data Syntax void *Ns_UrlSpecificGet( char *handle, char *method, char *url, int id ); Description The Ns_UrlSpecificGet function retrieves the best match that it can find. For instance, suppose you had previously registered a handle/method/url/id combination of {myserver, GET, /, 1} and {myserver, GET, /inventory, 1}. The following call, then, would match the data registered at {myserver, GET, /inventory, 1}: Ns_UrlSpecificGet("myserver", "GET", "/inventory/RJ45", 1) Examples See the example for Ns_UrlSpecificAlloc. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_UrlSpecificGetExact Overview Retrieve URL-specific data Syntax void *Ns_UrlSpecificGetExact( char *handle, char *method, char *url, int id, int flags ); Description The Ns_UrlSpecificGetExact function retrieves stored data for the exact specified method/URL/id combination and with the same inheritance setting. If the flags argument is set to NS_OP_NOINHERIT in Ns_UrlSpecificGetExact, the data stored with the NS_OP_NOINHERIT flag in Ns_UrlSpecificSet will be retrieved. If the flags argument is set to 0, the data stored without the NS_OP_NOINHERIT flag will be retrieved. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_UrlSpecificSet Overview Store URL-specific data for subsequent retrieval Syntax void Ns_UrlSpecificSet( char *handle, char *method, char *url, int id, void *data, int flags void (*deletefunc) (void *) ); Description The Ns_UrlSpecificSet function stores data in memory, allowing subsequent retrieval using handle, method, url, id, and inheritance flag. The flags argument can be NS_OP_NOINHERIT or NS_OP_NODELETE. You can store two sets of data based on the same handle, method, url, and id combination-- one set with inheritance on and one set with inheritance off. If the NS_OP_NOINHERIT flag is set, the data is stored based on the exact URL. If NS_OP_NOINHERIT is omitted, the data is stored based on the specified URL and any URL below it. In this case, Ns_UrlSpecificGetExact will match to the closest URL when retrieving the data. The deletefunc argument is called with data as an argument when this handle/url/method/id combination is re-registered or deleted, or when this server shuts down. unless NS_OP_NODELETE is set. Normally, calling Ns_UrlSpecificSet on a handle/url/method/id combination which already has an operation registered for it causes the previous operation's delete procedure to be called. You can override this behavior by adding the NS_OP_NODELETE flag. Examples See the example for Ns_UrlSpecificAlloc. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_UrlToFile Overview 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; } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_UTimedWaitForEvent Overview Wait for an event for a specified time, in microseconds Syntax int Ns_UTimedWaitForEvent( Ns_Event *event, Ns_Mutex *lock, int seconds, int microseconds ); Description Same as Ns_WaitForEvent except that it has a timeout in microseconds. On timeout, the function returns NS_TIMEOUT. On the Irix platform, the timeout granularity is still in seconds. In this case, if you specify a timeout of less than one second, it will be treated as one second. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_WaitForEvent Overview Wait for an event Syntax int Ns_WaitForEvent( Ns_Event * event, Ns_Mutex * lock ); Description Unlock the lock and wait for the event. This function blocks the current thread's execution until the event has been set and it can reacquire the lock. The mutex lock is locked before and after the call. Examples static int ready = 0; static Ns_Event ev; static Ns_Mutex lock; void Init(void) { Ns_InitializeMutex(&lock); Ns_InitializeEvent(&ev); } void Waiter(void) { Ns_LockMutex(&lock); if (!ready) { Ns_WaitForEvent(&ev, &lock); } Ns_UnlockMutex(&lock); ... resource ready ... } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_WaitForProcess Overview 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. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_WaitForSemaphore Overview Wait for a semaphore count to be greater than zero. Syntax int Ns_WaitForSemaphore( Ns_Semaphore * sema ); Description If the semaphore count is greater than zero, decrement it and continue. Otherwise, block until this is possible. Ns_SemaWait is the preferred function for waiting for a semaphore. Examples static Ns_Semaphore sem; void Init(void) { Ns_InitializeSemaphore(&sem, 0); } void Waiter(void) { Ns_WaitForSemaphore(&sem); ... access resource ... } void Releaser(void) { Ns_ReleaseSemaphore(&sem, 1); } [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_WaitForStartup Overview Block until server startup Syntax int Ns_WaitForStartup (void); Description Block until server startup. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_WaitForThread Overview Wait for a thread to exit Syntax int Ns_WaitForThread( Ns_Thread *thread ); Description This routine blocks the current thread's execution until the specified thread exits. Examples See the example for Ns_BeginThread. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_WaitProcess Overview 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. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_WaitThread Overview Wait for thread to exit Syntax int Ns_WaitThread ( Ns_Thread* thread, int* retcode ); Description This function blocks the current thread's execution until the specified thread exits. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_WriteConn Overview Send a specified length of data to the client Syntax int Ns_WriteConn( Ns_Conn *conn, char *buf, int len ); Description The Ns_WriteConn function performs the same function as Ns_ConnWrite, except that Ns_WriteConn guarantees to write as many bytes as are specified in len. It writes the specified length of data from the buffer to the client. [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_WriteLockRWLock Overview Acquire a write lock Syntax int Ns_WriteLockRWLock( Ns_RWLock *lock ); Description Ns_WriteLockRWLock acquires a write lock. Only one write lock can be in effect. If there are pending read locks active, the write lock acquisition blocks until all of the read locks drain. If a subsequent read lock acquisition attempt is made, the write lock has priority. For general information about read/write locks and an example showing the use of the read/write lock functions, see the Ns_InitializeRWLock function. Ns_RWLockWrLock is the preferred function for acquiring a write lock. See Also Ns_InitializeRWLock Ns_DestroyRWLock Ns_ReadLockRWLock Ns_ReadUnlockRWLock Ns_WriteUnlockRWLock [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc. Previous ToC Index Next [as-c-sm.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Ns_WriteUnlockRWLock Overview Release a write lock Syntax int Ns_WriteUnlockRWLock( Ns_RWLock *lock ); Description Ns_WriteUnlockRWLock releases a write lock. For general information about read/write locks and an example showing the use of the read/write lock functions, see the Ns_InitializeRWLock function. Ns_RWLockUnlock is the preferred function for releasing a lock. See Also Ns_InitializeRWLock Ns_DestroyRWLock Ns_ReadLockRWLock Ns_ReadUnlockRWLock Ns_WriteLockRWLock [bluebult.gif] Top of Page [bluebult.gif] [ Previous ] [ Contents ] [ Index ] [ Next ] Copyright © 1998-99 America Online, Inc.