$Header: /cvsroot/aolserver/aolserver.com/docs/devel/c/index.html,v 1.1 2002/03/07 19:15:35 kriston Exp $
    
    int Ns_AbsoluteUrl(
    Ns_DString *pds,
    char *url,
    char *baseurl
    );
    Ns_DString ds;
    Ns_DStringInit(&ds);
    Ns_AbsoluteUrl(&ds, "/foo/bar.html", "http://www.foo.com:1234/");
   The ds DString will contain "http://www.foo.com:1234/foo/bar.html".
    
    int Ns_AdpRegisterParser (
    char *name,
    Ns_AdpParserProc *newParserProc
    );
    typedef void (Ns_AdpParserProc)(Ns_DString *out, char *in);
The output should be formatted as a series of concatenated "chunks". A
   chunk is a string of the format:
     
 
NS_OK
 
The user's access is authorized.
 
NS_UNAUTHORIZED
 
Access is not public for this method or URL and either the user and
   password were not verified or the user does not have permission.
 
NS_FORBIDDEN
 
There is no possible user/password combination that would give
   authorization.
 
NS_ERROR
 
The authentication function could not perform the permission check.
 
 
 
 
 
 
The space for the string returned is located in the configuration
   data. You do not need to deallocate the string and you must not alter
   it.
 
 
The Ns_Set returned is located in the configuration data. You do not
   need to free the set and you must not alter it.
 
 
 
The space for the string returned is located in the configuration
   data. You must not deallocate or modify the string.
 
 
The space for the string returned is located in the configuration
   data. You must not deallocate or modify the string.
 
 
 
 
 
 
 
 
 
 
 
You can use Ns_GetRequest and the NS_OP_NODELETE flag for
   Ns_RegisterRequest to implement wrapper-type operation, where you save
   the operation function, delete procedure, and context and register a
   new function that does some type of pre-processing before calling the
   operation or delete procedures.
 
 
 
 
 
For example, Ns_NextWord("abc def") returns a pointer to the 'd' in
   that string.
 
 
 
 
 
 
<
 
<
 
>
 
>
 
&
 
&
 
 
It returns a pointer to the trace.
 
 
The why argument can be any of the following, or some combination of
   them by bitwise OR-ing (with "|") them together:
 
       NS_FILTER_PRE_AUTH: the filter will be called before
          authorization of a page
          NS_FILTER_POST_AUTH: the filter will be called after
          authorization but before a page has been returned
          NS_FILTER_TRACE: the filter will be called after the connection
          has been totally processed
          
   Using pre-authorization, the procedure will be called (assuming that
   the method/URL combination matches) just before authorization. If the
   procedure returns:
     * NS_OK: The server will continue to the next pre-authorization
       filter for this connection, or, if there are no more
       pre-authorization filters, it will continue on with authorization.
     * NS_FILTER_BREAK: The server will not process any more
       pre-authorization filters for this connection, and it will
       continue on with authorization.
     * NS_FILTER_RETURN: The server will close the connection and will
       not run any more pre-authorization filters. It will not authorize
       the request, and it will not run the function registered for this
       METHOD/URL. It WILL run any trace functions registered for this
       METHOD/URL, usually including logging. It is assumed that the
       filter has returned a proper response to the client before
       returning NS_FILTER_RETURN.
       
   Using post-authorization, the procedure will be called (assuming that
   the method/URL combination matches) just after successful
   authorization. If the procedure returns:
     * NS_OK: The server will continue to the next post-authorization
       filter for this connection, or, if there are no more
       post-authorization filters, it will run the function registered to
       handle this request.
     * NS_FILTER_BREAK: The server will not process any more
       post-authorization filters for this connection, and it will run
       the function registered to handle this request.
     * NS_FILTER_RETURN: The server will close the connection and will
       not run any more post-authorization filters and it will not run
       the function registered for this METHOD/URL. It WILL run any trace
       functions registered for this METHOD/URL, usually including
       logging. It is assumed that the filter has returned a proper
       response to the client before returning NS_FILTER_RETURN.
       
   Using trace, the procedure will be called (assuming that the
   method/URL combination match) after the connection has been totally
   processed and closed. If the procedure returns:
     * NS_OK: The server will continue to the next trace filter.
     * NS_FILTER_BREAK, NS_FILTER_RETURN: The rest of the trace filters
       are ignored
       
   The URLpatterns can contain standard string-matching characters. For
   example, these are valid URLpatterns:
 
       /employees/*.tcl
          /accounts/*/out
       
 
 
The server passes your procedure the context you specify here and the
   Ns_Conn structure associated with the new HTTP connection.
 
When a procedure is unregistered with either
   Ns_UnRegisterProxyRequest, the server calls the deleteProc with the
   same context. You can use this to do any cleanup you might require
   (e.g., close an index file or free something from the heap). If the
   value of deleteProc is NULL, the server does nothing.
 
 
The server passes your procedure the context you specify here and the
   Ns_Conn structure associated with the new HTTP connection.
 
When a procedure is unregistered with either Ns_UnRegisterRequest or
   by registering another procedure with the same method and URL, the
   server calls the deleteProc with the same context. You can use this to
   do any cleanup you might require (e.g., close an index file or free
   something from the heap). If the value of deleteProc is NULL, the
   server does nothing.
 
The flags parameter specifies one or more constants that can be OR'ed
   together. The available flags are NS_OP_NOINHERIT and NS_OP_NODELETE.
 
NS_OP_NOINHERIT tells AOLserver to only call your procedure if the URL
   matches exactly (the default behavior is to look for the closest
   match). You can register two procedures for the same method/URL
   combination by calling Ns_RegisterRequest once with NS_OP_NOINHERIT
   specified and once without NS_OP_NOINHERIT specified. The first
   procedure will be called if there is an exact match with the specified
   URL. The second procedure will be called if the requested URL is below
   the specified URL, provided there is not already another procedure
   registered with a closer match.
 
NS_OP_NODELETE specifies that the previous procedure's deleteproc
   should not be called. NS_OP_NODELETE can be used in conjunction with
   Ns_GetRequest to implement wrappers.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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";
     
 
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.
 
 
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.
 
 
 
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
       
 
 
 
 
 
 
 
Ns_AuthorizeRequest
Check access of a method and URL
Syntax
    
    int Ns_AuthorizeRequest(
    char *hServer,
    char *method,
    char *URL,
    char *authuser,
    char *authpasswd,
    char *ipaddr
    );
Description
The Ns_AuthorizeRequest function is used to call the function
   registered by Ns_SetRequestAuthorizeProc to authorize a user's access
   to the given method and URL. Possible return values are:
Ns_AuthorizeUser
Check username and password
Syntax
    
    int Ns_AuthorizeUser(
    char *user,
    char *passwd
    );
Description
Checks that the cleartext password is correct for the specified user.
   Returns NS_OK if it matches or NS_ERROR if not (or if no authorization
   procedure is registered).
Ns_ConfigGetBool
Get a boolean configuration file variable
Syntax
    
    int Ns_ConfigGetBool(
    char *hSection,
    char *sKey,
    int *pbValue
    );
Description
The Ns_ConfigGetBool function returns the boolean value of the
   specified key (sKey) in the specified configuration file section
   (hSection) and puts it into the integer pointed to by pbValue as a 1
   or 0. Values of "1", "y", "yes", "on", "t", and "true" are 1, and
   values of "0", "n", "no", "f", and "false" are 0. If any other value
   is found, a warning is written to the log and NS_FALSE is returned.
   Ns_ConfigGetBool returns NS_TRUE if a valid sKey exists and NS_FALSE
   otherwise.
Examples
        int opt;
        if (Ns_ConfigGetBool("MySect", "MyKey", &opt) != NS_TRUE) {
                /* Option was not present or invalid - set a default. */
                opt = 0;        /* off */
        }
   
Ns_ConfigGetInt
Get a configuration file integer variable
Syntax
    
    int Ns_ConfigGetInt(
    char *sectionName,
    char *key,
    int *valuePtr
    );
Description
This function converts the specified value into an int and stores it
   in valuePtr. If the key does not exist in the config file or it is not
   an integer, the function returns NS_FALSE. Otherwise it returns
   NS_TRUE.
Examples
        int n;
        if (Ns_ConfigGetInt("MySect", "MyKey", &n) != NS_TRUE) {
                /* Integer was not present or invalid - set a default. */
                n = 5;  /* off */
        }
   
Ns_ConfigGetInt64
Get a configuration file 64-bit integer variable
Syntax
    
    int Ns_ConfigGetInt64(
    char *hSection,
    char *key,
    INT64 *valuePtr
    );
Description
This function converts the specified value into an INT64 and stores it
   in valuePtr. If the key does not exist in the config file or it is not
   an integer, the function returns NS_FALSE. Otherwise it returns
   NS_TRUE.
Ns_ConfigGetPath
Return configuration file section name
Syntax
    
    char *Ns_ConfigGetPath(
    char *hServer,
    char *module,
    ...
    );
Description
The Ns_ConfigGetPath function returns a pointer to a configuration
   file section name based on the server (hServer) and module specified.
   The hServer or module may be NULL. A variable number of additional
   path elements are appended. The list must end with NULL. For example,
   Ns_ConfigGetPath("server1", NULL, "special", NULL) will return
   "\NS\Server\server1\special" if such a section exists in the
   configuration file and NULL if it does not.
Examples
    int
    Ns_ModuleInit(char *hServer, char *hModule)
    {
        char *path;
        char *value;
        /*
         * Construct the MySub section name specific to this
         * server and module. For example, if hServer = "vs1"
         * and hModule = "mymod", path would be:
         * [ns/server/vs1/module/mymod/MySudb]
         */
        path = Ns_ConfigGetPath(hServer, hModule, "MySub", NULL);
        value = Ns_ConfigGetValue(path, "MyKey");
        ...
   
Ns_ConfigGetSection
Get the Ns_Set for a configuration file section
Syntax
    
    Ns_Set *Ns_ConfigGetSection(
    char *sectionName
    );
Description
This function returns the entire section as an Ns_Set, where the
   fields of the set correspond to the entries of the section in the
   config file. The fields are stored in the Ns_Set in the same order in
   which they appear in the configuration file section. This is useful if
   you want to loop through all the entries of a section. If the section
   does not exist, Ns_ConfigGetSection returns NULL.
Examples
        Ns_Set *section;
        int i;
        char *key;
        /* Log the keys of the "MySection" config section. */
        section = Ns_ConfigGetSection("MySection");
        for (i = 0; i < Ns_SetSize(section); ++i) {
                key = Ns_SetKey(section, i);
                Ns_Log(Notice, "key %d: %s", i, key);
        }
        ...
   
Ns_ConfigGetSections
Return Ns_Sets with configuration file data
Syntax
    
    Ns_Set **Ns_ConfigGetSections(void);
Description
The Ns_ConfigGetSections function allocates and returns a
   null-terminated list of Ns_Sets. Each Ns_Set structure contains the
   configuration file data for a configuration file section.
Ns_ConfigGetValue
Get a configuration file variable
Syntax
    
    char *Ns_ConfigGetValue(
    char *sectionName,
    char *key
    );
Description
This function returns the value for the given key in the section named
   sectionName. If either the section does not exist or the key does not
   exist in the section, the function returns NULL. If multiple keys of
   the same name are in the named section (for example, the multiple Load
   lines of the Modules section), this function returns only the first
   matching entry. The section names must match exactly, but the key will
   be matched case-insensitively. Ns_ConfigGetValueExact is the
   case-sensitive counterpart of this function.
Examples
        /* Fetch the home directory of the AOLserver. */
        char *home;
        home = Ns_ConfigGetValue("ns/parameters", "Home");
   
Ns_ConfigGetValueExact
Get configuration variable case-sensitively
Syntax
    
    char *Ns_ConfigGetValueExact(
    char *sectionName,
    char *key,
    );
Description
The Ns_ConfigGetValueExact function is a case-sensitive counterpart to
   the Ns_ConfigGetValue function. It matches both the section name and
   the key case-sensitively. It returns the value for the given key in
   the section named sectionName.
Examples
   See the example for Ns_ConfigGetValue.
Ns_DecodeUrl
Decode URL query data
Syntax
    
    char *Ns_DecodeUrl(
    Ns_DString *pds,
    char *data
    );
Description
The Ns_DecodeUrl function decodes data that were encoded as URL query
   data. The decoded data are appended to the given Ns_DString. This
   function can be used to decode arguments that were passed as URL query
   data following a `?'. The return value is the value of pds->string,
   i.e., the address of the character array.
Ns_DStringAppend
Append a string to an Ns_DString
Syntax
    
    char *Ns_DStringAppend(
    Ns_DString *dsPtr,
    char *string
    );
Description
The Ns_DStringAppend macro appends the specified string plus a
   terminating null character to the end of the Ns_DString. 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
    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 */
   The resulting Ns_DString, ds, would contain "foo\0" and have a length
   of 3.
Ns_DStringAppendArg
Append argument to an Ns_DString
Syntax
    
    char *Ns_DStringAppendArg(
    Ns_DString *dsPtr,
    char *arg
    );
Description
Ns_EncodeUrl
Encode URL query data
Syntax
    
    char *Ns_EncodeUrl(
    Ns_DString *pds,
    char *data
    );
Description
The Ns_EncodeUrl function encodes the data as URL query data and
   appends the encoded data to the given Ns_DString. All characters
   except the alphanumerics are encoded as specified in RFC1738, Uniform
   Resource Locators. This function can be used to append arguments to a
   URL as query data following a `?'.
Ns_Encrypt
Encrypt key
Syntax
    
    char *Ns_Encrypt(
    char *key,
    char *salt,
    char buf[]
    );
Description
The Ns_Encrypt function encrypts the specified key, perturbed by salt.
   The result is returned in buf, which should be at least
   NS_ENCRYPT_BUFSIZE bytes in size.
Ns_FetchPage
Copy data from URL to dynamic string
Syntax
    
    int Ns_FetchPage(
    Ns_DString *pds,
    char *url,
    char *hServer
    );
Description
The Ns_FetchPage function copies data from url to the Ns_DString
   pointed to by pds. The URL must be relative and must correspond to a
   file served by this server. Ns_FetchPage returns a status of NS_OK or
   NS_ERROR.
Ns_FetchURL
Fetch a remote URL.
Syntax
    
    int Ns_FetchURL(
    Ns_DString *pds,
    char *URL,
    Ns_Set *headers
    );
Description
The Ns_FetchURL function connects the AOLserver to another HTTP Web
   server and requests the specified URL. The URL must be fully
   qualified. The content is appended to the given Ns_DString. If the
   headers is not NULL, the HTTP headers returned in the response from
   the remote server are appended to the set. Ns_FetchUrl does not
   currently handle redirects or requests for any protocol except HTTP.
   Use Ns_FetchPage to get pages on the local server.
Ns_FreeRequest
Free memory used by an Ns_Request
Syntax
    
    void Ns_FreeRequest(
    Ns_Request *request
    );
Description
The Ns_FreeRequest function frees the members of the Ns_Request and
   then frees the Ns_Request structure itself. The request is no longer
   valid and must not be used after a call to Ns_FreeRequest.
Ns_GetConnInterp
Get the Tcl interpreter for the connection
Syntax
    
    EXTERN Tcl_Interp *Ns_GetConnInterp(
    Ns_Conn *conn
    );
Description
This function, given the conn, returns the interpreter already
   assigned to the conn if one exists. If no interpreter is assigned, it
   allocates a new interpreter and assigns it to the conn. By using this
   function, you can be certain that the same interpreter (and its global
   state) are used by the registered request function and the filters.
Ns_GetMimeType
Get Mime type
Syntax
    
    char* Ns_GetMimeType (
    char* file
    );
Description
Guess the Mime type based on the filename extension. Case is ignored.
   The return value is of the form: "text/html".
Ns_GetRequest
Return the parameters of a request
Syntax
    
    typedef void *Ns_OpContext;
    typedef int (Ns_OpProc) (void *context, Ns_Conn *conn);
    typedef void (Ns_OpDeleteProc) (void *context);
    void Ns_GetRequest(
    char *hServer
    char *method,
    char *URL,
    Ns_OpProc **pProc,
    Ns_OpDeleteProc **pDeleteProc,
    Ns_OpContext **pContext
    int *pflags
    );
Description
The Ns_GetRequest function sets pproc to the procedure the server
   would call to handle a request of method and URL on the specified
   server. pContext is set to the context that would be passed to pProc
   when called, and pDeletepProc is set to the delete procedure that
   would be called if pProc were unregistered (or re-registered). pflags
   points to the flags argument passed to Ns_RegisterRequest. The
   function returned is the best matching function and not necessarily an
   exact matching function.
Ns_HtuuDecode
Perform base64 decode
Syntax
    
    int Ns_HtuuDecode (
    char* string,
    unsigned char* buf,
    int bufsize
    );
Description
Performs a base64 decode on string and writes the result into buf.
Ns_HtuuEncode
Perform base64 encode
Syntax
    
    int Ns_HtuuEncode (
    unsigned char* string,
    unsigned int bufsize,
    char* buf
    );
Description
Performs a base64 encode on string and writes the result into buf.
Ns_Match
Compare strings
Syntax
    
    char* Ns_Match (
    char* pattern,
    char* string
    );
Description
Compare the beginnings of two strings, case insensitively. The
   comparison stops when the end of the shorter string is reached.
Ns_NextWord
Find next word in string
Syntax
    
    char* Ns_NextWord (
    char* line
    );
Description
Find the next word (after whiteaspace) in a string.
Ns_ParseHeader
Parse Http headers
Syntax
    
    int Ns_ParseHeader (
    Ns_Set* psetHeaders,
    char* sHeader,
    ...
    );
Description
Parse http headers into the Ns_Set. The trailing arguments exist for
   backwards compatibility and are ignored.
Ns_ParseRequest
Parse an HTTP request line into an Ns_Request
Syntax
    
    Ns_Request *Ns_ParseRequest(
    char *requestLine
    );
Description
The Ns_ParseRequest function takes an HTTP request line and returns a
   newly allocated Ns_Request structure. You must eventually call
   Ns_FreeRequest to free the memory used by the Ns_Request structure and
   its members.
Ns_ParseUrl
Parse a URL
Syntax
    
    int Ns_ParseUrl(
    char *url,
    char **pprotocol,
    char **phost,
    char **pport,
    char **ppath,
    char **ptail
    );
Description
Parse a URL into its component parts. Pointers to the protocol, host,
   port, path, and "tail" (last path element) will be set by reference in
   the passed-in pointers. The passed-in url will be modified. Return
   NS_OK on success or NS_ERROR on failure.
Ns_PermPasswordCheck
Check user's encrypted password
Syntax
    
    int Ns_PermPasswordCheck(
    char *user,
    char *password
    );
Description
Validate a user's encrypted password. This function is only accessible
   if the nsperm module is loaded. NS_TRUE is returned if the password is
   correct.
Ns_QuoteHtml
Quote an HTML string
Syntax
    
    void Ns_QuoteHtml(
    Ns_DString *pds,
    char *string
    );
Description
The Ns_QuoteHtml function appends the given string to the Ns_DString,
   making the following substitutions that allow HTML to be included in
   another HTML page as plain text:
Ns_RegisterCleanup
Register a procedure for connection cleanup trace
Syntax
    
    void *Ns_RegisterCleanup(
    Ns_TraceProc *proc,
    void *arg
    );
Description
Register a connection cleanup trace procedure. Traces registered with
   this procedure are always called in LIFO order at the end of
   connection, regardless of the result code from the connection's
   request procedure. In other words, the procedure is called even if the
   client drops connection.
Ns_RegisterFilter
Register a filter function to handle a method/URL combination
Syntax
    
    typedef int (Ns_FilterProc) (void *context, Ns_Conn *conn, int
why);
    Ns_ProcHandle Ns_RegisterFilter(
    char *hServer,
    char *method,
    char *URLpatterns,
    Ns_FilterProc *proc,
    int why,
    void *context
    );
Description
This function will register a filter procedure for a method/URL
   combination on a server. This function will be called at the specified
   stage of a connection, if the method/URL combination for the filter
   matches the method/URL combination for the connection using glob style
   matching. The procedures are run in last-registered last-run order. A
   filter procedure is often used for logging.
Examples
    static int
    ReportUse(void *context, Ns_Conn *conn, int why){
     int status=NS_OK;
     switch(why){
      case NS_FILTER_PRE_AUTH:
       Ns_Log(Notice, "User trying to access %s",conn->request->url);
         break;
        case NS_FILTER_POST_AUTH:
          Ns_Log(Notice, "User authorized to access %s",conn->request-
>url);
          break;
        case NS_FILTER_TRACE:
          Ns_Log(Notice, "User has retrieved %s",conn->request->url);
          break;
        default:
          status=NS_ERROR;
      }
      return status;
    }
    int
    Ns_ModuleInit(char *hServer, char *hModule){
      Ns_RegisterFilter(hServer, "GET", "/test/a*", ReportUse,
        Ns_FILTER_PRE_AUTH, NULL);
      Ns_RegisterFilter(hServer, "GET", "/test/b*", ReportUse,
        Ns_FILTER_POST_AUTH, NULL);
      Ns_RegisterFilter(hServer, "GET", "/test/c*", ReportUse,
        Ns_FILTER_TRACE, NULL);
      Ns_RegisterFilter(hServer, "GET", "/test/d*", ReportUse,
        Ns_FILTER_PRE_AUTH | NS_FILTER_POST_AUTH, NULL);
      Ns_RegisterFilter(hServer, "GET", "/test/e*", ReportUse,
        Ns_FILTER_POST_AUTH | NS_FILTER_TRACE, NULL);
      Ns_RegisterFilter(hServer, "GET", "/test/f*", ReportUse,
        Ns_FILTER_PRE_AUTH | Ns_FILTER_POST_AUTH | NS_FILTER_TRACE,
NULL);
   
Ns_RegisterProxyRequest
Register a function to proxy requests for a method/protocol
   combination
Syntax
    
    typedef void *Ns_OpContext;
    typedef int (Ns_OpProc) (void *context, Ns_Conn *conn);
    typedef void (Ns_OpDeleteProc) (void *context);
    void Ns_RegisterProxyRequest(
    char        *Server,
    char        *method,
    char        *protocol,
    Ns_OpProc   *proc,
    Ns_Callback *deleteProc,
    void        *context
    );
Description
The Ns_RegisterProxyRequest function registers function proc to handle
   HTTP requests. When the specified server receives a proxy request, it
   finds the appropriate registered function.
Examples
   See the example in the examples/c/nsproxy directory.
Ns_RegisterRequest
Register one or two functions to handle HTTP requests for a method/URL
   combination
Syntax
    
    typedef void *Ns_OpContext;
    typedef int (Ns_OpProc) (void *context, Ns_Conn *conn);
    typedef void (Ns_OpDeleteProc) (void *context);
    void Ns_RegisterRequest(
    char *hServer,
    char *method,
    char *URL,
    Ns_OpProc *proc,
    Ns_OpDeleteProc *deleteProc,
    Ns_OpContext context,
    int flags
    );
Description
The Ns_RegisterRequest function registers function proc to handle HTTP
   requests. When the specified server receives an HTTP request, it finds
   the most specific registered operation. The default operation for a
   GET (i.e., the one registered with URL \Q/') serves up a page out of
   the file system.
Ns_RegisterReturn
Register a return status for a URL
Syntax
    
    void Ns_RegisterReturn (
    int status,
    char* url
    );
Description
Associate a URL with a return status (for custom error pages). For
   exmaple:
    Ns_RegisterReturn(404, "http://www.foo.com/notfound.html");
   will send redirects to http://www.foo.com/notfound.html whenever a 404
   error is to be returned.
Ns_RegisterServerTrace
Register a trace procedure for a server.
Syntax
    
    typedef void (Ns_TraceProc) (void *context, Ns_Conn *conn);
    Ns_ProcHandle Ns_RegisterServerTrace(
    char *hServer,
    Ns_TraceProc *proc,
    void *context
    );
Description
The Ns_RegisterServerTrace function registers proc as a trace for the
   specified server. The server calls all trace procedures after every
   HTTP connection with the context and the Ns_Conn for that connection.
   The procedures are run in last-registered first-run order. A trace
   procedure is often used for logging.
Ns_RelativeUrl
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");
   
Ns_SkipUrl
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);
    }
   
Ns_StrCaseFind
Perform strstr
Syntax
    
    char* Ns_StrCaseFind (
    char* string,
    char* substr
    );
Description
This function performs a case-insensitive strstr(3C).
Ns_StrCopy
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.
Ns_StrDup
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.
Ns_StringPrint
Print string
Syntax
    
    void Ns_StringPrint (
    char* s
    );
Description
This function prints the specified string to stdout.
Ns_Strtok
Perform strtok_r
Syntax
    
    char* Ns_Strtok (
    char* s1,
    const char* s2
    );
Description
This function wraps strtok_r(3C).
Ns_StrToLower
Lowercase string
Syntax
    
    char* Ns_StrToLower (
    char* string
    );
Description
This function converts the specified string to lowercase.
Ns_StrToUpper
Uppercase string
Syntax
    
    char* Ns_StrToUpper (
    char* string
    );
Description
This function converts the specified string to uppercase.
Ns_StrTrim
Trim string
Syntax
    
    char* Ns_StrTrim (
    char* string
    );
Description
This function trims all blanks from the specified string.
Ns_StrTrimLeft
Trim blanks from left
Syntax
    
    char* Ns_StrTrimLeft (
    char* string
    );
Description
This function trims all blanks from the left of the string.
Ns_StrTrimRight
Trim blanks from right
Syntax
    
    char* Ns_StrTrimRight (
    char* string
    );
Description
This function trims all blanks from the right of the string.
Ns_TclAllocateInterp
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.
Ns_TclAppendInt
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).
Ns_TclDeAllocateInterp
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.
Ns_TclDestroyInterp
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.
Ns_TclEval
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.
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)
   
Ns_TclGetOpenChannel
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).
Ns_TclGetOpenFd
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.
Ns_TclInitInterps
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);
   
Ns_TclInitModule
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.
Ns_TclInterpServer
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.
Ns_TclLibrary
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".
Ns_TclLogError
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.
Ns_TclMarkForDelete
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.
Ns_UnRegisterProxyRequest
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.
Ns_UnRegisterRequest
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.