AOLserver

# Data Structure C Library Functions

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

Append the specified argument plus a terminating null character to the end of the Ns_DString. It is useful for making strings like: "foo\0bar\0baz\0". It returns the string associated with the current Ns_DString.

## Ns_DStringExport

Export the string of an Ns_DString

### Syntax

        char *Ns_DStringExport(
        Ns_DString *src
        );

### Description

The Ns_DStringExport function returns the current Ns_DString string and leaves the Ns_DString in the initialized state. The string returned needs to be freed eventually with Ns_Free.

### Examples

        Ns_DString ds;
        char *stringdest;
        Ns_DStringInit(&ds);
        Ns_DStringAppend(&ds, "foo");
        stringdest = Ns_DStringExport(&ds);
        /* do something with `stringdest' */
        Ns_Free(stringdest);

## Ns_DStringFree

Free any allocated memory used by an Ns_DString

### Syntax

        void Ns_DStringFree(
        Ns_DString *dsPtr
        );

### Description

The Ns_DStringFree function frees any memory associated with an Ns_DString.

### Examples

        Ns_DString ds;
        Ns_DStringInit(&ds);
        Ns_DStringAppend(&ds, "foo");
        /* do something with the dstring */
        printf ("%s\n", ds.string);
        Ns_DStringFree(&ds); /* finished with dstring */

## Ns_DStringInit

Initialize an Ns_DString

### Syntax

        void Ns_DStringInit(
        Ns_DString *dsPtr
        );

### Description

Before using an Ns_DString, you must initialize it with Ns_DStringInit. Storage for a Ns_DString is often on the stack in the calling function. The example below shows a typical usage.

### Examples

        int MyFunctions(int a, int b)
        {
            Ns_DString ds;
            Ns_DStringInit(&ds);
            /* ds is now initialized and ready to pass to
              another function */
            ...
        }

## Ns_DStringLength

Return the current length of an Ns_DString

### Syntax

        int Ns_DStringLength(
        Ns_DString *dsPtr
        );

### Description

The Ns_DStringLength macro returns the current length of the Ns_DString.

### Examples

        Ns_DString ds;
        Ns_DStringInit(&ds);
        Ns_DStringAppend(&ds, "");
        printf("len=%d\n", Ns_DStringLength(&ds));
        Ns_DStringFree(&ds); /* finished with dstring */

## Ns_DStringNAppend

Append n-characters of a string to an Ns_DString

### Syntax

        char *Ns_DStringNAppend(
        Ns_DString *dsPtr,
        char *string,
        int length
        );

### Description

The Ns_DStringNAppend function appends a string up to the specified number of characters, plus a terminating null character.( Unlike the Tcl_DStringAppend function, which only works with string data, the AOLserver Ns_DStringNAppend function can append binary data.) The string may overflow from static space to the heap as a result of calling this function. It returns the string associated with the current Ns_DString.

### Examples

       The resulting Ns_DString in this example, ds, would contain "foo\0"
       and have a length of 3:
        Ns_DString ds;
        Ns_DStringInit(&ds);
        Ns_DStringNAppend(&ds, "fooasdf", 3);
        printf("%s\n", ds.string);
        Ns_DStringFree(&ds); /* finished with dstring */

       If you need a null-terminated list of null-terminated strings, such as
       "foo\0bar\0\0", you would add one to the length of the appended
       strings to get the extra terminating null character. For example:
        Ns_DString ds;
        Ns_DStringInit(&ds);
        Ns_DStringNAppend(&ds, "foo", 4);
        Ns_DStringNAppend(&ds, "bar", 4);

## Ns_DStringPrintf

Append a formatted string to an Ns_DString

### Syntax

        char *Ns_DStringPrintf(
        Ns_DString *dsPtr,
        char *fmt,
        ...
        );

### Description

The Ns_DStringPrintf function appends a string that has been created by calling the sprintf function with the given format and optional arguments. This function currently uses a fixed length buffer of 1024 characters to sprintf() the data before appending to the Ns_DString.

### Examples

        Ns_DString ds;

        Ns_DStringInit(&ds);
        Ns_DStringPrintf(&ds, "/path%d", getpid());
        /* do something with dstring */
        printf ("%s\n", ds.string);
        Ns_DStringFree(&ds); /* finished with dstring */

## Ns_DStringTrunc

Truncate an Ns_DString

### Syntax

        void Ns_DStringTrunc(
        Ns_DString *dsPtr,
        int length
        );

### Description

The Ns_DStringTrunc function truncates an Ns_DString to the given length. Unlike Ns_DStringFree, which truncates the Ns_DString to length 0 and frees any memory that may have been allocated on the heap, Ns_DStringTrunc allows you to truncate the string to any length. It maintains any memory allocated on the heap. This function is useful in a loop where the Ns_DString is likely to overflow the static space each time through. Using Ns_DStringTrunc instead of Ns_DStringFree will avoid having the Ns_DString call malloc to obtain the addition space in each iteration. You will need to call Ns_DStringFree eventually to free any space that may have been allocated for the Ns_DString.

### Examples

        Ns_DString ds;
        int i;

        Ns_DStringInit(&ds);
        for (i=0; i < 50; i++) {
            Ns_DStringPrintf(&ds, "%s%d", "aBigString", i);
            /* do something with the dstring constructed above*/
            Ns_DStringTrunc(&ds, 0);
        }

        Ns_DStringFree(&ds); /* finished with dstring */

## Ns_DStringValue

Return the current value of an Ns_DString

### Syntax

        char *Ns_DStringValue(
        Ns_DString *dsPtr
        );

### Description

The Ns_DStringValue macro returns a pointer to the current value of an Ns_DString. This may be a pointer to the Ns_DString's static space or to a string allocated on the heap if the static space has overflowed. It is not safe to use the value returned by this macro after an intervening call to Ns_DStringAppend because the Ns_DString string could overflow to or move within the heap.

### Examples

        Ns_DString ds;
        Ns_DStringInit(&ds);
        Ns_DStringAppend(&ds, "foo");
        /* do something with the dstring */
        printf ("%s\n", Ns_DStringValue(&ds));
        Ns_DStringFree(&ds); /* finished with dstring */

## Ns_DStringVarAppend

Append a variable number of strings to an Ns_DString

### Syntax

        char *Ns_DStringVarAppend(
        Ns_DString *dsPtr,
        ...
        );

### Description

The Ns_DStringVarAppend function appends a variable number of strings to an Ns_DString. The list must end with NULL.

### Examples

        Ns_DString ds;
        Ns_DStringInit(&ds);
        Ns_DStringVarAppend(&ds, "foo", "bar", NULL);
        /* do something with the dstring */
        printf ("%s\n", ds.string);
        Ns_DStringFree(&ds); /* finished with dstring */

## Ns_QueryToSet

Parse query data into Ns_Set

### Syntax

        int Ns_QueryToSet (
        char* query,
        Ns_Set* set
        );

### Description

Parse query data (such as "a=b&c=d&jkl=rew") into an Ns_Set.

## Ns_ServerSpecificAlloc

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.

## Ns_ServerSpecificDestroy

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.

## Ns_ServerSpecificGet

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.

## Ns_ServerSpecificSet

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.

## Ns_SetCopy

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);

## Ns_SetCreate

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);

## Ns_SetDelete

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);

## Ns_SetDeleteKey

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);

## Ns_SetDriverProc

Set socket driver callback

### Syntax

        int Ns_SetDriverProc (
        Ns_Driver driver,
        Ns_DrvId id,
        void* proc
        );

### Description

Set a single socket driver callback procedure.

## Ns_SetEvent

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.

## Ns_SetFind

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);

## Ns_SetFree

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);

## Ns_SetGet

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);

## Ns_SetIDeleteKey

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);

## Ns_SetIFind

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);

## Ns_SetIGet

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);

## Ns_SetIUnique

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

## Ns_SetKey

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);

## Ns_SetLast

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.

## Ns_SetListFind

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.

## Ns_SetListFree

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.

## Ns_SetMerge

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.

## Ns_SetMove

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.

## Ns_SetName

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.

## Ns_SetPrint

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.

## Ns_SetPut

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);

## Ns_SetPutValue

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.

## Ns_SetRequestAuthorizeProc

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.

## Ns_SetRequestUrl

Fill in request structure

### Syntax

        void Ns_SetRequestUrl (
        Ns_Request* request,
        char* url
        );

### Description

Fill in a request structure.

## Ns_SetSize

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.

## Ns_SetSplit

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.

## Ns_SetTrunc

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);

## Ns_SetUnique

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.

## Ns_SetUpdate

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.

## Ns_SetValue

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.

## Ns_TclEnterSet

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);

## Ns_TclFreeSet

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.

## Ns_TclGetSet

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.

## Ns_TclGetSet2

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.

## Ns_UrlSpecificAlloc

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;
        }

## Ns_UrlSpecificDestroy

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

## Ns_UrlSpecificGet

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.

## Ns_UrlSpecificGetExact

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.

## Ns_UrlSpecificSet

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.