File: three.html

package info (click to toggle)
aolserver4 4.5.1-18.1
links: PTS, VCS
area: main
in suites: stretch
size: 12,008 kB
sloc: ansic: 45,126; tcl: 5,533; sh: 1,037; makefile: 380; pascal: 219; php: 13
file content (4701 lines) | stat: -rw-r--r-- 112,237 bytes
parent folder | download | duplicates (8)

   #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.