File: c-ch3.htm

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 (2918 lines) | stat: -rw-r--r-- 98,792 bytes
parent folder | download | duplicates (16)
<!--plsfield:text-->
<HTML><HEAD>
<TITLE>C API Reference  -- C API Function Categories</TITLE>
<LINK rel=Previous href="c-ch2.htm">
<LINK rel=ToC href="toc.htm">
<LINK rel=Index href="master.htm">
<LINK rel=Next href="c-ch4.htm">
</HEAD><BODY BGCOLOR="#ffffff"><A NAME="topofpage"></A>
<TABLE WIDTH=100%>
  <TR>
    <TD ALIGN=LEFT>
      <A NAME="topofpage"></A> <IMG  SRC="as-c-sm.gif">
    </TD>
    <TD ALIGN=RIGHT>
      <A href="c-ch2.htm"><IMG  BORDER="0" src=navbprev.gif alt="[ Previous ]"></A>
      <A href=toc.htm> <IMG  BORDER="0" src=navbhome.gif alt="[ Contents ]"></A>
      <A href=master.htm> <IMG  BORDER="0" src=navbhelp.gif alt="[ Index ]"></A>
      <A href="c-ch4.htm"> <IMG  BORDER="0" src=navbnext.gif alt="[ Next ]"></A>
      <A name="7983"> </A>
    </TD>
  </TR>
</TABLE>

<a name="27557">
</a><h3>C API Function Categories</h3>
<p><a name="13990">
</a>The C API functions fall into these categories, which are described in the sections that follow:<Table Border = "3">
<tr><td><p><a name="13995">
</a><a href="c-ch3.htm#4941">Memory Allocation Functions</a></p>
<td><p><a name="13998">
</a>A set of wrapper functions for the malloc family of memory allocation functions that attempt to recover automatically from a low-memory situation.</p>

<tr><td><p><a name="14002">
</a><a href="c-ch3.htm#33229">Data Structures and Related Functions</a></p>
<td><p><a name="14005">
</a>Data structures and related functions for manipulating data common in HTTP connection requests and working with active HTTP connections.</p>

<tr><td><p><a name="14009">
</a><a href="c-ch3.htm#33932">Core Functions</a></p>
<td><p><a name="14015">
</a>An extensive set of functions for interacting with AOLserver.</p>

<tr><td><p><a name="14019">
</a><a href="c-ch3.htm#37064">Database Functions</a></p>
<td><p><a name="14022">
</a>A set of functions for accessing the database and obtaining information about the database.</p>


</Table></p>
<a name="4941">
</a><h4>Memory Allocation Functions</h4>
<p><a name="4943">
</a>The AOLserver uses dynamically allocated memory extensively. To ease the burden of checking for memory-allocation failures, the AOLserver provides wrapper functions for the malloc family of memory allocation functions.</p>
<p><a name="4945">
</a>The AOLserver functions differ from their system counterparts: instead of returning NULL on memory-allocation failure, they instead attempt to recover automatically from a low-memory situation. The AOLserver attempts to recover by first freeing any memory from internal caches that can safely be flushed. If flushing caches fails to free enough memory, the AOLserver will wait 1 second and then, if necessary, another 10 seconds, in the hope that the memory shortage is temporary, perhaps caused by another program that will shortly stop executing. If the AOLserver cannot recover from a low-memory situation, it logs the failure and shuts down the server.</p>
<p><a name="32971">
</a>Using the AOLserver memory allocation functions is a matter replacing the corresponding malloc family system function with a function of the same name preceded by ns_. You can currently mix calls to the ns_ functions and their system counterparts. However, this is not recommended because the interface may change in future releases of AOLserver. </p>
<p><a name="35611">
</a>The memory allocation functions are listed below.<Table Border = "3">
<tr><th><p><a name="273858">
</a><b>Function</b></p>
<th><p><a name="273860">
</a><b>Description</b></p>

<tr><td><p><a name="33023">
</a><a href="c-ch42.htm#87483">Ns_Calloc</a></p>
<td><p><a name="33025">
</a>Allocate a zero-filled block of memory </p>

<tr><td><p><a name="33027">
</a><a href="c-ch193.htm#123060">Ns_Free</a></p>
<td><p><a name="33029">
</a>Free a block of allocated memory </p>

<tr><td><p><a name="33031">
</a><a href="c-ch248.htm#125390">Ns_Malloc</a></p>
<td><p><a name="33033">
</a>Allocate a block of memory </p>

<tr><td><p><a name="33035">
</a><a href="c-ch284.htm#126636">Ns_Realloc</a></p>
<td><p><a name="33037">
</a>Resize a previously allocated block of memory </p>

<tr><td><p><a name="33039">
</a><a href="c-ch371.htm#305491">Ns_StrCopy</a></p>
<td><p><a name="33041">
</a>Copy a string or NULL value using Ns_Malloc </p>

<tr><td><p><a name="33043">
</a><a href="c-ch372.htm#131837">Ns_StrDup</a></p>
<td><p><a name="33045">
</a>Copy a string using Ns_Malloc </p>


</Table></p>
<a name="33229">
</a><h4>Data Structures and Related Functions</h4>
<p><a name="33233">
</a>The AOLserver C API provides the following data structures for manipulating data common in HTTP connection requests and working with active HTTP connections.<Table Border = "3">
<tr><td><p><a name="33238">
</a><a href="c-ch3.htm#33265">Ns_Set Structure</a></p>
<td><p><a name="33241">
</a>A string key-value pair structure, such as for database rows, HTTP header information, and HTTP form data.</p>

<tr><td><p><a name="33245">
</a><a href="c-ch3.htm#33393">Ns_DString Structure</a></p>
<td><p><a name="33248">
</a>A structure used to implement dynamic memory blocks, typically strings.</p>

<tr><td><p><a name="33252">
</a><a href="c-ch3.htm#33642">Ns_Conn Structure</a></p>
<td><p><a name="33255">
</a>A structure that includes all state information of an active HTTP connection.</p>

<tr><td><p><a name="33259">
</a><a href="c-ch3.htm#33672">Ns_Request Structure</a></p>
<td><p><a name="33262">
</a>A structure that contains the various parts of the HTTP request of an active connection.</p>


</Table></p>
<a name="33265">
</a><h4>Ns_Set Structure</h4>
<p><a name="33269">
</a>An AOLserver C API function must often access data as sets of key-value pairs, for example:</p>
<ul>
<li>a row of data from the database<a name="33270">
</a>
<p><li>HTTP header information<a name="33271">
</a>
<p><li>HTML form data<a name="33272">
</a>
<p></ul>
<p><a name="33273">
</a>The Ns_Set structure provides a convenient mechanism for manipulating key-value pairs of string data. The key-value pairs in an Ns_Set are Ns_SetFields (called "fields" for short). The Ns_SetField structure has the following definition:</p>
<pre>    <a name="33274"></a>
    <a name="33275"></a>typedef struct {
    <a name="33276"></a>	char *name;		  /* Key name of field. */
    <a name="33277"></a>	char *value;		 /* Value of field (can be NULL) */
    <a name="33278"></a>} Ns_SetField;
    <a name="33279"></a>
</pre><p><p><a name="33280">
</a>The Ns_Set structure has the following definition:</p>
<pre>    <a name="33281"></a>
    <a name="33282"></a>typedef struct {
    <a name="33283"></a>	char 	*name;    	/* Name of set (can be NULL) */
    <a name="33284"></a>	int   size;    		/* Current number of fields */
    <a name="33285"></a>	int   maxSize;			 /* (used internally) */
    <a name="33286"></a>	Ns_SetField *fields; 	/* Array of Ns_SetField's */
    <a name="33287"></a>} Ns_Set;
    <a name="33288"></a>
</pre><p><p><a name="33289">
</a>Within the Ns_Set, the fields are stored as an array, in the order in which the fields were added to the set. The array of fields grows dynamically as fields are entered.</p>
<p><a name="33290">
</a>To access the fields of a set, either use the lookup functions described below or loop through the fields directly as in the following code fragment:</p>
<pre>    <a name="33291"></a>
    <a name="33292"></a>	for (n = 0; n &lt; Ns_SetSize(set); ++n) {
    <a name="33293"></a>		printf("field %d name: %s value: %s\n",
    <a name="33294"></a>			n, Ns_SetKey(set, n), Ns_SetValue(set, n));
    <a name="33295"></a>	}
</pre><p><p><a name="34620">
</a>The functions that use the Ns_Set data structure are listed in the following table.<Table Border = "3">
<tr><th><p><a name="273894">
</a><b>Function</b></p>
<th><p><a name="273896">
</a><b>Description</b></p>

<tr><td><p><a name="39391">
</a><a href="c-ch321.htm#129429">Ns_SetCopy</a></p>
<td><p><a name="39393">
</a>Create a new copy of a set </p>

<tr><td><p><a name="39395">
</a><a href="c-ch322.htm#129543">Ns_SetCreate</a></p>
<td><p><a name="39397">
</a>Create a new Ns_Set </p>

<tr><td><p><a name="157165">
</a><a href="c-ch323.htm#129655">Ns_SetDelete</a></p>
<td><p><a name="39401">
</a>Remove a field from a set by field index </p>

<tr><td><p><a name="39403">
</a><a href="c-ch324.htm#129765">Ns_SetDeleteKey</a></p>
<td><p><a name="39405">
</a>Remove a field from a set by key name </p>

<tr><td><p><a name="39407">
</a><a href="c-ch327.htm#129873">Ns_SetFind</a></p>
<td><p><a name="39409">
</a>Locate the index of a field within an Ns_Set </p>

<tr><td><p><a name="39411">
</a><a href="c-ch328.htm#129977">Ns_SetFree</a></p>
<td><p><a name="39413">
</a>Free memory used by an Ns_Set </p>

<tr><td><p><a name="39415">
</a><a href="c-ch329.htm#130079">Ns_SetGet</a></p>
<td><p><a name="39417">
</a>Return the value for a field </p>

<tr><td><p><a name="39419">
</a><a href="c-ch330.htm#130179">Ns_SetIDeleteKey</a></p>
<td><p><a name="39421">
</a>Remove a field from a set by key name case-insentively </p>

<tr><td><p><a name="39423">
</a><a href="c-ch331.htm#130277">Ns_SetIFind</a></p>
<td><p><a name="39425">
</a>Locate the index of a field case-insensitively </p>

<tr><td><p><a name="39427">
</a><a href="c-ch332.htm#130373">Ns_SetIGet</a></p>
<td><p><a name="39429">
</a>Return the value for a field case-insensitively </p>

<tr><td><p><a name="288179">
</a><a href="c-ch333.htm#290048">Ns_SetIUnique</a></p>
<td><p><a name="288181">
</a>Check if a key in an Ns_Set is unique (case insensitive)</p>

<tr><td><p><a name="39431">
</a><a href="c-ch334.htm#130467">Ns_SetKey</a></p>
<td><p><a name="39433">
</a>Return the key name of a field </p>

<tr><td><p><a name="39435">
</a><a href="c-ch335.htm#130559">Ns_SetLast</a></p>
<td><p><a name="39437">
</a>Return the index of the last element of a set </p>

<tr><td><p><a name="39439">
</a><a href="c-ch336.htm#130649">Ns_SetListFind</a></p>
<td><p><a name="39441">
</a>Locate a set by name in a set list </p>

<tr><td><p><a name="39443">
</a><a href="c-ch337.htm#130737">Ns_SetListFree</a></p>
<td><p><a name="39445">
</a>Free a list of sets </p>

<tr><td><p><a name="39447">
</a><a href="c-ch338.htm#130823">Ns_SetMerge</a></p>
<td><p><a name="39449">
</a>Merge two sets </p>

<tr><td><p><a name="39451">
</a><a href="c-ch339.htm#130907">Ns_SetMove</a></p>
<td><p><a name="39453">
</a>Move fields from one set to the end of another </p>

<tr><td><p><a name="39455">
</a><a href="c-ch340.htm#130989">Ns_SetName</a></p>
<td><p><a name="39457">
</a>Return the name of a set </p>

<tr><td><p><a name="39459">
</a><a href="c-ch341.htm#131069">Ns_SetPrint</a></p>
<td><p><a name="39461">
</a>Print the contents of a set to the AOLserver error log </p>

<tr><td><p><a name="39463">
</a><a href="c-ch342.htm#131147">Ns_SetPut</a></p>
<td><p><a name="39465">
</a>Add a field to an Ns_Set </p>

<tr><td><p><a name="39467">
</a><a href="c-ch343.htm#131223">Ns_SetPutValue</a></p>
<td><p><a name="39469">
</a>Set the value of a field </p>

<tr><td><p><a name="39471">
</a><a href="c-ch346.htm#131369">Ns_SetSize</a></p>
<td><p><a name="39473">
</a>Return the current size of a set </p>

<tr><td><p><a name="39475">
</a><a href="c-ch347.htm#131439">Ns_SetSplit</a></p>
<td><p><a name="39477">
</a>Split a set into an array of new sets </p>

<tr><td><p><a name="39479">
</a><a href="c-ch349.htm#131507">Ns_SetTrunc</a></p>
<td><p><a name="39481">
</a>Truncate an Ns_Set </p>

<tr><td><p><a name="288189">
</a><a href="c-ch350.htm#290133">Ns_SetUnique</a></p>
<td><p><a name="288191">
</a>Check if a key in an Ns_Set is unique (case sensitive)</p>

<tr><td><p><a name="619392">
</a><a href="c-ch351.htm#619759">Ns_SetUpdate</a></p>
<td><p><a name="619394">
</a>Update an Ns_Set value</p>

<tr><td><p><a name="39483">
</a><a href="c-ch354.htm#131625">Ns_SetValue</a></p>
<td><p><a name="39485">
</a>Return the value of a field </p>

<tr><td><p><a name="288402">
</a><a href="c-ch384.htm#290202">Ns_TclEnterSet</a></p>
<td><p><a name="288404">
</a>Make an Ns_Set accessible through Tcl</p>

<tr><td><p><a name="288217">
</a><a href="c-ch386.htm#290257">Ns_TclFreeSet</a></p>
<td><p><a name="288219">
</a>Free an Ns_Set</p>

<tr><td><p><a name="288210">
</a><a href="c-ch390.htm#290270">Ns_TclGetSet</a></p>
<td><p><a name="288212">
</a>Return the Ns_Set for the specified set ID</p>

<tr><td><p><a name="288203">
</a><a href="c-ch391.htm#290282">Ns_TclGetSet2</a></p>
<td><p><a name="288205">
</a>Return the Ns_Set for the specified set ID in a pointer</p>


</Table></p>
<a name="33393">
</a><h4>Ns_DString Structure</h4>
<p><a name="33397">
</a>An AOLserver C API function often uses dynamically allocated strings. The Ns_DString structure is used for this purpose. (The AOLserver Ns_DString is based on the Tcl_DString found in the Tcl C API.) Ns_DStrings contains a small amount of static space but will overflow to allocated memory if needed. Within the AOLserver, pointers to Ns_DStrings are often used where other APIs would require a pointer to a buffer and a specific size.</p>
<p><a name="33407">
</a>The Ns_DString structure has the following definition:</p>
<pre>    <a name="33408"></a>typedef struct {
    <a name="33409"></a>  char *string;    /* Points to either static space or dynamically
    <a name="33410"></a>                      allocated memory */
    <a name="33411"></a>  int length;      /* Number of bytes in string */
    <a name="33412"></a>  int spaceAvl;    /* Number of bytes unused but allocated for
    <a name="33413"></a>                      string */
    <a name="33414"></a>  char staticspace [NS_DSTRING_STATIC_SIZE]; 
    <a name="33415"></a>                   /* Initial static space. */
    <a name="33416"></a>} Ns_DString;
</pre><p><p><a name="33417">
</a>NS_DSTRING_STATIC_SIZE is by default set to 512 bytes.</p>
<p><a name="36765">
</a>The functions that use the Ns_DString data structure are listed in the following table.<Table Border = "3">
<tr><td><p><a name="562678">
</a><a href="c-ch169.htm#562022">Ns_DStringAppend</a></p>
<td><p><a name="562680">
</a>Append a string to an Ns_DString </p>

<tr><td><p><a name="584424">
</a><a href="c-ch170.htm#584441">Ns_DStringAppendArg</a></p>
<td><p><a name="584426">
</a>Append argument to an Ns_DString</p>

<tr><td><p><a name="39194">
</a><a href="c-ch171.htm#119580">Ns_DStringExport</a></p>
<td><p><a name="39196">
</a>Export the string of an Ns_DString </p>

<tr><td><p><a name="39198">
</a><a href="c-ch172.htm#119842">Ns_DStringFree</a></p>
<td><p><a name="39200">
</a>Free any allocated memory used by an Ns_DString </p>

<tr><td><p><a name="39202">
</a><a href="c-ch173.htm#120102">Ns_DStringInit</a></p>
<td><p><a name="39204">
</a>Initialize an Ns_DString </p>

<tr><td><p><a name="562685">
</a><a href="c-ch174.htm#562239">Ns_DStringLength</a></p>
<td><p><a name="562687">
</a>Return the current length of an Ns_DString </p>

<tr><td><p><a name="39210">
</a><a href="c-ch175.htm#120616">Ns_DStringNAppend</a></p>
<td><p><a name="39212">
</a>Append n-characters of a string to an Ns_DString </p>

<tr><td><p><a name="39214">
</a><a href="c-ch176.htm#120870">Ns_DStringPrintf</a></p>
<td><p><a name="39216">
</a>Append a formatted string to an Ns_DString </p>

<tr><td><p><a name="39218">
</a><a href="c-ch177.htm#121122">Ns_DStringTrunc</a></p>
<td><p><a name="39220">
</a>Truncate an Ns_DString </p>

<tr><td><p><a name="562700">
</a><a href="c-ch178.htm#562458">Ns_DStringValue</a></p>
<td><p><a name="562702">
</a>Return the current value of an Ns_DString </p>

<tr><td><p><a name="39226">
</a><a href="c-ch179.htm#121620">Ns_DStringVarAppend</a></p>
<td><p><a name="39228">
</a>Append a variable number of strings to an Ns_DString </p>


</Table></p>
<a name="33642">
</a><h4>Ns_Conn Structure</h4>
<p><a name="33646">
</a>All functions that handle connection requests, which we refer to as AOLserver <i>operations, </i>take as an argument a pointer to an Ns_Conn structure. This structure contains all information and state about the active connection. The public members that you may find useful include:</p>
<pre>    <a name="33647"></a>typedef struct Ns_Conn {
<pre>    <a name="33648"></a>Ns_Request *request;
</pre><p></pre><p><p><a name="33649">
</a>Pointer to an Ns_Request structure that holds information about the HTTP request associated with the connection. The Ns_Request structure is described below.</p>
<pre>    <a name="33650"></a>Ns_Set *headers;
</pre><p><p><a name="33651">
</a>Pointer to an Ns_Set whose fields are the HTTP request headers sent by the HTTP client.</p>
<pre>    <a name="33652"></a>Ns_Set *outputheaders;
</pre><p><p><a name="33653">
</a>Pointer to an Ns_Set whose fields are the headers to be sent to the client.</p>
<pre>    <a name="33654"></a>char *authUser;
</pre><p><p><a name="33657">
</a>Decoded user name from the header information. Because the AOLserver does not authenticate the user when world permission is allowed to a URL, this user may not be a valid AOLserver user.</p>
<pre>    <a name="33662"></a>char *authPasswd;
</pre><p><p><a name="33663">
</a>Decoded user password from the header information. Because the AOLserver does not authenticate the user when world permission is allowed to a URL, this password may not be the user's actual password.</p>
<pre>    <a name="33667"></a>int contentLength;
</pre><p><p><a name="33668">
</a>Number of bytes in the content sent by the HTTP client.</p>
<pre>    <a name="33669"></a>} Ns_Conn;
</pre><p><a name="33672">
</a><h4>Ns_Request Structure</h4>
<p><a name="33673">
</a>The Ns_Request structure breaks a complete HTTP request line into its many parts.</p>
<pre>    <a name="33674"></a>typedef struct Ns_Request {
<pre>    <a name="33675"></a>char *line;
</pre><p></pre><p><p><a name="33676">
</a>A copy of the actual request line sent by the HTTP client.</p>
<pre>    <a name="33677"></a>char *method;
</pre><p><p><a name="33678">
</a>HTTP method; for example GET or POST.</p>
<pre>    <a name="33679"></a>char *protocol;
</pre><p><p><a name="33680">
</a>Protocol of the HTTP request, e.g., http or ftp. Normally, this element is NULL because the AOLserver does not currently proxy requests, so fully-qualified URLs in HTTP requests are rejected.</p>
<pre>    <a name="33684"></a>char *host;
</pre><p><p><a name="33685">
</a>Host part of the URL in the HTTP request. Normally this element is NULL because the AOLserver does not currently proxy HTTP requests.</p>
<pre>    <a name="33689"></a>unsigned short port;
</pre><p><p><a name="33690">
</a>Port explicitly specified in the URL of the HTTP request. This element is 0 when no port is explicitly specified.</p>
<pre>    <a name="33691"></a>char *url;
</pre><p><p><a name="33692">
</a>URL after having been normalized with Ns_NormalizePath() function and after removing any query data that may have been appended.</p>
<pre>    <a name="33693"></a>char *query;
</pre><p><p><a name="33697">
</a>Any query data appended to the URL. (Query data are any data that follow a question mark at the end of a URL. They can be used to pass arguments to an operation.)</p>
<pre>    <a name="33698"></a>int urlc;
</pre><p><p><a name="33699">
</a>Number of path elements in the normalized URL. This is similar to the argc parameter to the main() function in a C program. For example, if the URL were <code>/some/url</code>, urlc would be 2.</p>
<pre>    <a name="33700"></a>char **urlv;
</pre><p><p><a name="33701">
</a>NULL-terminated array of pointers to strings for each path element of the normalized URL. This is similar to the argv parameter to the main() function in a C program. For example, if the URL was <code>/some/url</code>, urlv[0] would be "some", urlv[1] would be "url", and urlv[2] would be NULL.</p>
<pre>    <a name="33702"></a>double version;
</pre><p><p><a name="33703">
</a>Version of the HTTP request, usually 0.9 or 1.0.</p>
<pre>    <a name="33704"></a>} Ns_Request;
</pre><p><p><a name="36771">
</a>The AOLserver provides several convenient functions for working with the elements of the Ns_Request structure. The functions that use the Ns_Request data structure are listed in the following table.<Table Border = "3">
<tr><td><p><a name="39133">
</a><a href="c-ch194.htm#123292">Ns_FreeRequest</a></p>
<td><p><a name="39135">
</a>Free memory used by an Ns_Request </p>

<tr><td><p><a name="39137">
</a><a href="c-ch269.htm#126114">Ns_ParseRequest</a></p>
<td><p><a name="39139">
</a>Parse an HTTP request line into an Ns_Request </p>

<tr><td><p><a name="620360">
</a><a href="c-ch345.htm#620363">Ns_SetRequestUrl</a></p>
<td><p><a name="620362">
</a>Fill in request structure</p>

<tr><td><p><a name="39141">
</a><a href="c-ch358.htm#131735">Ns_SkipUrl</a></p>
<td><p><a name="39143">
</a>Skip past path elements in the URL of a request </p>


</Table></p>
<a name="33932">
</a><h4>Core Functions</h4>
<p><a name="34034">
</a>The groups of core functions listed below are described in the following subsections.<Table Border = "3">
<tr><td><p><a name="33937">
</a><a href="c-ch3.htm#34036">Registration Functions</a></p>
<td><p><a name="33940">
</a>Functions used to register other functions to handle HTTP requests or implement traces, chores, or shutdown procedures.</p>

<tr><td><p><a name="33944">
</a><a href="c-ch3.htm#34118">Access Control Functions</a></p>
<td><p><a name="33947">
</a>Functions used to check authorization on a method/URL combination or implement an alternative authorization procedure.</p>

<tr><td><p><a name="529526">
</a><a href="c-ch3.htm#529537">Caching Functions</a></p>
<td><p><a name="529528">
</a>Functions used to manage caching.</p>

<tr><td><p><a name="562723">
</a><a href="c-ch3.htm#562780">Configuration File Functions</a></p>
<td><p><a name="562726">
</a>Functions used to access the in-memory representation of the configuration file data.</p>

<tr><td><p><a name="33951">
</a><a href="c-ch3.htm#34131">URL and File Functions</a></p>
<td><p><a name="33954">
</a>Functions used to convert URLs to files within the pages directory and test the files for various properties</p>

<tr><td><p><a name="33958">
</a><a href="c-ch3.htm#34149">HTTP Header-Related Functions</a></p>
<td><p><a name="33961">
</a>Functions used to generate and send HTTP headers to a browser</p>

<tr><td><p><a name="33965">
</a><a href="c-ch3.htm#34162">HTTP Complete Response Functions</a></p>
<td><p><a name="33968">
</a>Functions used to generate complete responses to HTTP requests</p>

<tr><td><p><a name="33972">
</a><a href="c-ch3.htm#34252">HTTP Simple Response Functions</a></p>
<td><p><a name="33975">
</a>Functions used to call Ns_ConnReturnStatus or Ns_ConnReturnNotice with the appropriate status code, reason, and notice message when the only response required by the AOLserver is the HTTP status line.</p>

<tr><td><p><a name="33982">
</a><a href="c-ch3.htm#40195">HTTP Low-Level Connection Functions</a></p>
<td><p><a name="33985">
</a>Functions used to send data directly to the client without formatting or immediate buffering of the data.</p>

<tr><td><p><a name="33997">
</a><a href="c-ch3.htm#34402">Logging Functions</a></p>
<td><p><a name="34002">
</a>Functions used to write information to the AOLserver log file.</p>

<tr><td><p><a name="569462">
</a><a href="c-ch3.htm#569484">Memory Pool Functions</a></p>
<td><p><a name="569464">
</a>Functions used to manipulate the memory pools used by AOLserver.</p>

<tr><td><p><a name="34006">
</a><a href="c-ch3.htm#34411">Mime-Related Functions</a></p>
<td><p><a name="34009">
</a>Functions used to access and manipulate Mime type information.</p>

<tr><td><p><a name="615771">
</a><a href="c-ch3.htm#615783">Module Logging Realms Functions</a></p>
<td><p><a name="615773">
</a>Functions used to control realms for module logging.</p>

<tr><td><p><a name="288426">
</a><a href="c-ch3.htm#288454">Scheduled Procedures Functions</a></p>
<td><p><a name="288428">
</a>Functions used to schedule procedures to be run daily, weekly, or at specified intervals.</p>

<tr><td><p><a name="288430">
</a><a href="c-ch3.htm#288490">Sockets Interface Functions</a></p>
<td><p><a name="288432">
</a>Functions for managing sockets.</p>

<tr><td><p><a name="781365">
</a><a href="c-ch3.htm#34419">Socket Driver Interface Functions</a></p>
<td><p><a name="781367">
</a>Functions for socket drivers.</p>

<tr><td><p><a name="34013">
</a><a href="c-ch3.htm#757634">Storage and Retrieval Functions</a></p>
<td><p><a name="34016">
</a>Functions used to store and retrieve information specific to URLs or  servers.</p>

<tr><td><p><a name="735595">
</a><a href="c-ch3.htm#700157">Synchronization Functions</a></p>
<td><p><a name="735598">
</a>Functions used to manage condition variables, semaphores, mutexes, events, critical sections, and read/write locks.</p>

<tr><td><p><a name="34020">
</a><a href="c-ch3.htm#34428">Thread Interface Functions</a></p>
<td><p><a name="34023">
</a>Functions used to interact with the threads interface of AOLserver.</p>

<tr><td><p><a name="370896">
</a><a href="c-ch3.htm#371209">Tcl Interpreter Functions</a></p>
<td><p><a name="370898">
</a>Functions used to allocate and return Tcl interpreters.</p>

<tr><td><p><a name="34030">
</a><a href="c-ch3.htm#34476">Miscellaneous Functions</a></p>
<td><p><a name="34033">
</a>Functions used to perform miscellaneous tasks and get information about the server.</p>


</Table> </p>
<a name="34036">
</a><h4>Registration Functions</h4>
<p><a name="34037">
</a>At startup time, the server loads your C module and runs your initialization function. Your initialization function can connect to any external data sources or initialize any data structures it requires. The initialization function then typically calls one or more of the following functions to register other functions within the module as capable of handling URL requests or implementing traces, chores, or shutdown procedures.</p>
<p><a name="36778">
</a>The functions in this category are listed in the following table.<Table Border = "3">
<tr><td><p><a name="861550">
</a><a href="c-ch8.htm#861558">Ns_AdpRegisterParser</a></p>
<td><p><a name="861552">
</a>Register a parser for ADPs</p>

<tr><td><p><a name="39028">
</a><a href="c-ch205.htm#124200">Ns_GetRequest</a></p>
<td><p><a name="39030">
</a>Return the parameters of a request </p>

<tr><td><p><a name="39032">
</a><a href="c-ch287.htm#126806">Ns_RegisterAtExit</a></p>
<td><p><a name="39034">
</a>Register an exit procedure. </p>

<tr><td><p><a name="617903">
</a><a href="c-ch288.htm#618091">Ns_RegisterAtPreStartup</a></p>
<td><p><a name="617905">
</a>Register a procedure for pre-server startup</p>

<tr><td><p><a name="617907">
</a><a href="c-ch289.htm#618092">Ns_RegisterAtSignal</a></p>
<td><p><a name="617909">
</a>Register a procedure at HUP signal</p>

<tr><td><p><a name="617911">
</a><a href="c-ch290.htm#618093">Ns_RegisterAtStartup</a></p>
<td><p><a name="617913">
</a>Register a procedure for server startup</p>

<tr><td><p><a name="857372">
</a><a href="c-ch291.htm#857378">Ns_RegisterCleanup</a></p>
<td><p><a name="857374">
</a>Register a procedure for connection cleanup trace</p>

<tr><td><p><a name="368827">
</a><a href="c-ch293.htm#368833">Ns_RegisterFilter</a></p>
<td><p><a name="368829">
</a>Register a filter function to handle a method/URL combination</p>

<tr><td><p><a name="861110">
</a><a href="c-ch295.htm#857871">Ns_RegisterProxyRequest</a></p>
<td><p><a name="861112">
</a>Register a function to proxy requests for a method/protocol combination</p>

<tr><td><p><a name="39036">
</a><a href="c-ch296.htm#860948">Ns_RegisterRequest</a></p>
<td><p><a name="39038">
</a>Register a function to handle HTTP requests for a method/URL combination </p>

<tr><td><p><a name="617918">
</a><a href="c-ch297.htm#617924">Ns_RegisterReturn</a></p>
<td><p><a name="617920">
</a>Register a return status for a URL</p>

<tr><td><p><a name="39040">
</a><a href="c-ch298.htm#127140">Ns_RegisterServerShutdown</a></p>
<td><p><a name="39042">
</a>Register a shutdown procedure for a server. </p>

<tr><td><p><a name="39044">
</a><a href="c-ch299.htm#127304">Ns_RegisterServerTrace</a></p>
<td><p><a name="39046">
</a>Register a trace procedure for a server. </p>

<tr><td><p><a name="39048">
</a><a href="c-ch300.htm#127466">Ns_RegisterShutdown</a></p>
<td><p><a name="39050">
</a>Register a shutdown procedure. </p>

<tr><td><p><a name="861480">
</a><a href="c-ch417.htm#861488">Ns_UnRegisterProxyRequest</a></p>
<td><p><a name="861482">
</a>Unregister a proxy request function</p>

<tr><td><p><a name="39052">
</a><a href="c-ch418.htm#131885">Ns_UnRegisterRequest</a></p>
<td><p><a name="39054">
</a>Unregister a function </p>


</Table></p>
<a name="34118">
</a><h4>Access Control Functions</h4>
<p><a name="34119">
</a>The hierarchical access checking authorization system is accessed through the following functions.<Table Border = "3">
<tr><td><p><a name="38982">
</a><a href="c-ch11.htm#45199">Ns_AuthorizeRequest</a></p>
<td><p><a name="38984">
</a>Check access of a method and URL </p>

<tr><td><p><a name="588984">
</a><a href="c-ch12.htm#589000">Ns_AuthorizeUser</a></p>
<td><p><a name="588986">
</a>Check username and password</p>

<tr><td><p><a name="857614">
</a><a href="c-ch272.htm#857625">Ns_PermPasswordCheck</a></p>
<td><p><a name="857616">
</a>Check user's encrypted password</p>

<tr><td><p><a name="38990">
</a><a href="c-ch344.htm#131297">Ns_SetRequestAuthorizeProc</a></p>
<td><p><a name="38992">
</a>Set function used by Ns_AuthorizeRequest </p>

<tr><td><p><a name="588988">
</a><a href="c-ch353.htm#589349">Ns_SetUserAuthorizeProc</a></p>
<td><p><a name="588990">
</a>Set function used by Ns_AuthorizeUser</p>


</Table></p>
<a name="529537">
</a><h4>Caching Functions</h4>
<p><a name="529555">
</a>Caching is managed with the following functions:<Table Border = "3">
<tr><td><p><a name="529545">
</a><a href="c-ch17.htm#536069">Ns_CacheBroadcast</a></p>
<td><p><a name="529547">
</a>Broadcast to condition variable</p>

<tr><td><p><a name="535901">
</a><a href="c-ch18.htm#536070">Ns_CacheCreate</a></p>
<td><p><a name="535903">
</a>Create a new cache</p>

<tr><td><p><a name="535905">
</a><a href="c-ch19.htm#536071">Ns_CacheCreateEntry</a></p>
<td><p><a name="535907">
</a>Create a cache entry</p>

<tr><td><p><a name="536060">
</a><a href="c-ch20.htm#536072">Ns_CacheCreateSz</a></p>
<td><p><a name="536062">
</a>Create a size-based cache</p>

<tr><td><p><a name="535909">
</a><a href="c-ch21.htm#536073">Ns_CacheDeleteEntry</a></p>
<td><p><a name="535911">
</a>Delete a cache entry</p>

<tr><td><p><a name="535913">
</a><a href="c-ch22.htm#536074">Ns_CacheFind</a></p>
<td><p><a name="535915">
</a>Find a cache</p>

<tr><td><p><a name="535917">
</a><a href="c-ch23.htm#536075">Ns_CacheFindEntry</a></p>
<td><p><a name="535919">
</a>Find a cache entry</p>

<tr><td><p><a name="535921">
</a><a href="c-ch24.htm#536076">Ns_CacheFirstEntry</a></p>
<td><p><a name="535923">
</a>Get first cache entry</p>

<tr><td><p><a name="535925">
</a><a href="c-ch25.htm#536077">Ns_CacheFlush</a></p>
<td><p><a name="535927">
</a>Flush all cache entries</p>

<tr><td><p><a name="535929">
</a><a href="c-ch26.htm#536078">Ns_CacheFlushEntry</a></p>
<td><p><a name="535931">
</a>Delete a cache entry</p>

<tr><td><p><a name="535933">
</a><a href="c-ch27.htm#536079">Ns_CacheFree</a></p>
<td><p><a name="535935">
</a>Free allocated memory</p>

<tr><td><p><a name="535937">
</a><a href="c-ch28.htm#536080">Ns_CacheGetValue</a></p>
<td><p><a name="535939">
</a>Get value of cache entry</p>

<tr><td><p><a name="535941">
</a><a href="c-ch29.htm#536081">Ns_CacheKey</a></p>
<td><p><a name="535943">
</a>Get key of cache entry</p>

<tr><td><p><a name="535945">
</a><a href="c-ch30.htm#536082">Ns_CacheLock</a></p>
<td><p><a name="535947">
</a>Lock a cache</p>

<tr><td><p><a name="535949">
</a><a href="c-ch31.htm#536083">Ns_CacheMalloc</a></p>
<td><p><a name="535951">
</a>Allocate memory</p>

<tr><td><p><a name="535953">
</a><a href="c-ch32.htm#536084">Ns_CacheName</a></p>
<td><p><a name="535955">
</a>Get name of cache</p>

<tr><td><p><a name="535957">
</a><a href="c-ch33.htm#536085">Ns_CacheNextEntry</a></p>
<td><p><a name="535959">
</a>Get next cache entry</p>

<tr><td><p><a name="535961">
</a><a href="c-ch34.htm#536086">Ns_CacheSetValue</a></p>
<td><p><a name="535963">
</a>Set value of cache entry</p>

<tr><td><p><a name="535965">
</a><a href="c-ch35.htm#536087">Ns_CacheSetValueSz</a></p>
<td><p><a name="535967">
</a>Set value of cache entry and adjust cache size</p>

<tr><td><p><a name="535969">
</a><a href="c-ch36.htm#536088">Ns_CacheSignal</a></p>
<td><p><a name="535971">
</a>Signal cache's condition variable</p>

<tr><td><p><a name="535973">
</a><a href="c-ch37.htm#536089">Ns_CacheTimedGetValue</a></p>
<td><p><a name="535975">
</a>Wait for cache entry to be set</p>

<tr><td><p><a name="535977">
</a><a href="c-ch38.htm#536090">Ns_CacheTimedWait</a></p>
<td><p><a name="535979">
</a>Wait for condition variable to be set</p>

<tr><td><p><a name="535981">
</a><a href="c-ch39.htm#537174">Ns_CacheUnlock</a></p>
<td><p><a name="535983">
</a>Unlock cache</p>

<tr><td><p><a name="535985">
</a><a href="c-ch40.htm#536092">Ns_CacheUnsetValue</a></p>
<td><p><a name="535987">
</a>Reset cache entry to null</p>

<tr><td><p><a name="535989">
</a><a href="c-ch41.htm#536093">Ns_CacheWait</a></p>
<td><p><a name="535991">
</a>Wait indefinitely for condition variable to be set</p>


</Table></p>
<a name="562780">
</a><h4>Configuration File Functions</h4>
<p><a name="562784">
</a>When the server is started, it reads the AOLserver configuration file into memory. You can use the following functions to access the in-memory representation of those data.  See <a href="con-ch.htm#103550">Chapter 4</a> in the <i>AOLserver Administrator's Guide</i> for more information on the AOLserver configuration file.<Table Border = "3">
<tr><td><p><a name="562799">
</a><a href="c-ch51.htm#303896">Ns_ConfigGetBool</a></p>
<td><p><a name="562801">
</a>Get a boolean configuration file variable </p>

<tr><td><p><a name="562806">
</a><a href="c-ch52.htm#205495">Ns_ConfigGetInt</a></p>
<td><p><a name="562808">
</a>Get a configuration file integer variable </p>

<tr><td><p><a name="574092">
</a><a href="c-ch53.htm#205598">Ns_ConfigGetInt64</a></p>
<td><p><a name="574094">
</a>Get a configuration file 64-bit integer variable</p>

<tr><td><p><a name="562813">
</a><a href="c-ch54.htm#88863">Ns_ConfigGetPath</a></p>
<td><p><a name="562815">
</a>Return configuration file section name </p>

<tr><td><p><a name="562820">
</a><a href="c-ch55.htm#89317">Ns_ConfigGetSection</a></p>
<td><p><a name="562822">
</a>Get the Ns_Set for a configuration file section </p>

<tr><td><p><a name="562827">
</a><a href="c-ch56.htm#89769">Ns_ConfigGetSections</a></p>
<td><p><a name="562829">
</a>Return Ns_Sets with configuration file data </p>

<tr><td><p><a name="562834">
</a><a href="c-ch57.htm#213787">Ns_ConfigGetValue</a></p>
<td><p><a name="562836">
</a>Get a configuration file variable </p>

<tr><td><p><a name="562841">
</a><a href="c-ch58.htm#90667">Ns_ConfigGetValueExact</a></p>
<td><p><a name="562843">
</a>Get configuration variable case-sensitively </p>


</Table></p>
<a name="34131">
</a><h4>URL and File Functions</h4>
<p><a name="34135">
</a>AOLserver operations often work with files within the pages directory. These files normally are related to URLs that are requested by clients. The AOLserver provides the following functions for converting URLs to files within the pages directory and testing the files for various properties.<Table Border = "3">
<tr><td><p><a name="38755">
</a><a href="c-ch5.htm#330845">Ns_AbsoluteUrl</a></p>
<td><p><a name="38757">
</a>Construct a URL from a URL and location </p>

<tr><td><p><a name="38759">
</a><a href="c-ch161.htm#119042">Ns_DecodeUrl</a></p>
<td><p><a name="38761">
</a>Decode URL query data </p>

<tr><td><p><a name="38763">
</a><a href="c-ch181.htm#332643">Ns_EncodeUrl</a></p>
<td><p><a name="38765">
</a>Encode URL query data </p>

<tr><td><p><a name="335709">
</a><a href="c-ch214.htm#335562">Ns_HomePath</a></p>
<td><p><a name="335714">
</a>Construct a path name relative to the AOLserver home directory </p>

<tr><td><p><a name="38779">
</a><a href="c-ch247.htm#125204">Ns_MakePath</a></p>
<td><p><a name="38781">
</a>Construct a path name from a list of path elements </p>

<tr><td><p><a name="338525">
</a><a href="c-ch258.htm#338386">Ns_ModulePath</a></p>
<td><p><a name="338527">
</a>Construct a path from base path </p>

<tr><td><p><a name="38783">
</a><a href="c-ch265.htm#125936">Ns_NormalizePath</a></p>
<td><p><a name="38785">
</a>Normalize a path name </p>

<tr><td><p><a name="38787">
</a><a href="c-ch271.htm#126290">Ns_PathIsAbsolute</a></p>
<td><p><a name="38789">
</a>Check for an absolute path name </p>

<tr><td><p><a name="617270">
</a><a href="c-ch280.htm#617276">Ns_QueryToSet</a></p>
<td><p><a name="617272">
</a>Parse query data into Ns_Set</p>

<tr><td><p><a name="38791">
</a><a href="c-ch301.htm#127475">Ns_RelativeUrl</a></p>
<td><p><a name="38793">
</a>Get relative filename portion of URL </p>

<tr><td><p><a name="38795">
</a><a href="c-ch352.htm#131567">Ns_SetUrlToFileProc</a></p>
<td><p><a name="38797">
</a>Customize relative file mapping </p>

<tr><td><p><a name="38799">
</a><a href="c-ch420.htm#131963">Ns_UrlIsDir</a></p>
<td><p><a name="38801">
</a>Check if a directory that corresponds to a URL exists </p>

<tr><td><p><a name="38803">
</a><a href="c-ch421.htm#131999">Ns_UrlIsFile</a></p>
<td><p><a name="38805">
</a>Check if a file that corresponds to a URL exists </p>

<tr><td><p><a name="38811">
</a><a href="c-ch427.htm#132195">Ns_UrlToFile</a></p>
<td><p><a name="38813">
</a>Construct the filename that corresponds to a URL </p>


</Table></p>
<a name="34149">
</a><h4>HTTP Header-Related Functions</h4>
<p><a name="34150">
</a>The C API includes the following functions to generate and send HTTP headers to a browser. If the original request was not HTTP version 1.0 or higher, these functions do not send the headers to the client. This allows you to write header generating code without regard to HTTP version.<Table Border = "3">
<tr><td><p><a name="38580">
</a><a href="c-ch62.htm#92427">Ns_ConnCondSetHeaders</a></p>
<td><p><a name="38582">
</a>Set the value for a header field conditionally </p>

<tr><td><p><a name="788841">
</a><a href="c-ch63.htm#213931">Ns_ConnConstructHeaders</a></p>
<td><p><a name="788843">
</a>Put HTTP header into DString</p>

<tr><td><p><a name="38584">
</a><a href="c-ch73.htm#95001">Ns_ConnFlushHeaders</a></p>
<td><p><a name="38586">
</a>Mark the end of the headers </p>

<tr><td><p><a name="788853">
</a><a href="c-ch81.htm#789890">Ns_ConnOutputHeaders</a></p>
<td><p><a name="788855">
</a>Get Ns_Set of headers to send to client</p>

<tr><td><p><a name="38588">
</a><a href="c-ch85.htm#98704">Ns_ConnPrintfHeader</a></p>
<td><p><a name="38590">
</a>Return a formatted header </p>

<tr><td><p><a name="38592">
</a><a href="c-ch91.htm#100292">Ns_ConnReplaceHeaders</a></p>
<td><p><a name="38594">
</a>Replace output headers for connection </p>

<tr><td><p><a name="38596">
</a><a href="c-ch119.htm#104964">Ns_ConnSetExpiresHeader</a></p>
<td><p><a name="38598">
</a>Return an "expires" header for the given time </p>

<tr><td><p><a name="38600">
</a><a href="c-ch120.htm#105328">Ns_ConnSetHeaders</a></p>
<td><p><a name="38602">
</a>Set the value for a header field </p>

<tr><td><p><a name="38604">
</a><a href="c-ch121.htm#105690">Ns_ConnSetLastModifiedHeader</a></p>
<td><p><a name="38606">
</a>Return a last modified header using the given time </p>

<tr><td><p><a name="38608">
</a><a href="c-ch122.htm#106050">Ns_ConnSetLengthHeader</a></p>
<td><p><a name="38610">
</a>Return a Content-Length header </p>

<tr><td><p><a name="38612">
</a><a href="c-ch123.htm#106764">Ns_ConnSetRequiredHeaders</a></p>
<td><p><a name="38614">
</a>Return the required HTTP headers </p>

<tr><td><p><a name="38616">
</a><a href="c-ch124.htm#107118">Ns_ConnSetTypeHeader</a></p>
<td><p><a name="38618">
</a>Return a Content-Type header </p>


</Table></p>
<a name="34162">
</a><h4>HTTP Complete Response Functions</h4>
<p><a name="34163">
</a>The following functions can be used to generate complete responses to HTTP requests.<Table Border = "3">
<tr><td><p><a name="38491">
</a><a href="c-ch94.htm#101462">Ns_ConnReturnAdminNotice</a></p>
<td><p><a name="38493">
</a>Return a short notice to a client to contact system administrator </p>

<tr><td><p><a name="361975">
</a><a href="c-ch96.htm#361767">Ns_ConnReturnData</a></p>
<td><p><a name="362258">
</a>Return an HTML string to a client</p>

<tr><td><p><a name="38495">
</a><a href="c-ch97.htm#101861">Ns_ConnReturnFile</a></p>
<td><p><a name="38497">
</a>Return a file to a client </p>

<tr><td><p><a name="38499">
</a><a href="c-ch99.htm#102258">Ns_ConnReturnHtml</a></p>
<td><p><a name="38501">
</a>Return an HTML string to a client </p>

<tr><td><p><a name="38503">
</a><a href="c-ch103.htm#151706">Ns_ConnReturnNotice</a></p>
<td><p><a name="38505">
</a>Return a short notice to a client </p>

<tr><td><p><a name="38507">
</a><a href="c-ch108.htm#103085">Ns_ConnReturnOpenFd</a></p>
<td><p><a name="38509">
</a>Return a file to a client </p>

<tr><td><p><a name="38511">
</a><a href="c-ch109.htm#103463">Ns_ConnReturnOpenFile</a></p>
<td><p><a name="38513">
</a>Return a file to a client </p>

<tr><td><p><a name="38515">
</a><a href="c-ch110.htm#103839">Ns_ConnReturnRedirect</a></p>
<td><p><a name="38517">
</a>Return an HTTP redirect response to a client </p>

<tr><td><p><a name="38519">
</a><a href="c-ch111.htm#104213">Ns_ConnReturnStatus</a></p>
<td><p><a name="38521">
</a>Return a status message to a client </p>


</Table></p>
<a name="34252">
</a><h4>HTTP Simple Response Functions</h4>
<p><a name="40174">
</a>Often the only response required by the AOLserver is the HTTP status line. For example, after a successful PUT of a new file, the only required response is the status line to indicate if the file was successfully saved on the server. The following functions call Ns_ConnReturnStatus or Ns_ConnReturnNotice with the appropriate status code, reason, and/or notice message:<Table Border = "3">
<tr><td><p><a name="349009">
</a><a href="c-ch95.htm#101848">Ns_ConnReturnBadRequest</a></p>
<td><p><a name="349011">
</a>The request was invalid. Status = 400</p>

<tr><td><p><a name="349016">
</a><a href="c-ch98.htm#102245">Ns_ConnReturnForbidden</a></p>
<td><p><a name="349018">
</a>The request is forbidden. There is no Authorization header that will authorize access from this IP address. Status = 403</p>

<tr><td><p><a name="349023">
</a><a href="c-ch100.htm#102640">Ns_ConnReturnInternalError</a></p>
<td><p><a name="349025">
</a>A server internal error occurred. Status = 500</p>

<tr><td><p><a name="349037">
</a><a href="c-ch101.htm#353725">Ns_ConnReturnNoResponse</a></p>
<td><p><a name="349039">
</a>The request requires no response. Status = 204</p>

<tr><td><p><a name="349044">
</a><a href="c-ch102.htm#133843">Ns_ConnReturnNotFound</a></p>
<td><p><a name="349046">
</a>The requested URL was not found on the server. Status = 404</p>

<tr><td><p><a name="349051">
</a><a href="c-ch104.htm#103046">Ns_ConnReturnNotImplemented</a></p>
<td><p><a name="349053">
</a>The request has not been implemented by the server. Status = 500</p>

<tr><td><p><a name="349030">
</a><a href="c-ch105.htm#103059">Ns_ConnReturnNotModified</a></p>
<td><p><a name="349032">
</a>The requested data have not been modified since the time specified by the If-Modified-Since header sent by the client. Status = 304</p>

<tr><td><p><a name="40301">
</a><a href="c-ch106.htm#103072">Ns_ConnReturnOk</a></p>
<td><p><a name="40303">
</a>The request was successful. Status = 200</p>

<tr><td><p><a name="40317">
</a><a href="c-ch112.htm#104585">Ns_ConnReturnUnauthorized</a></p>
<td><p><a name="40319">
</a>The request did not include a valid Authorization header or the header did not specify an authorized user. Status = 401</p>

<tr><td><p><a name="788869">
</a><a href="c-ch113.htm#790164">Ns_ConnRunRequest</a></p>
<td><p><a name="788871">
</a>Execute procedure for method and URL pattern</p>


</Table></p>
<a name="40195">
</a><h4>HTTP Low-Level Connection Functions</h4>
<p><a name="34329">
</a>The following functions can be used to send data directly to the client. No formatting or immediate buffering is done to the data.<Table Border = "3">
<tr><td><p><a name="38237">
</a><a href="c-ch59.htm#91113">Ns_ConnAuthPasswd</a></p>
<td><p><a name="38239">
</a>Return password </p>

<tr><td><p><a name="38241">
</a><a href="c-ch60.htm#91553">Ns_ConnAuthUser</a></p>
<td><p><a name="38243">
</a>Return user name </p>

<tr><td><p><a name="38245">
</a><a href="c-ch61.htm#91991">Ns_ConnClose</a></p>
<td><p><a name="38247">
</a>Close a connection </p>

<tr><td><p><a name="38249">
</a><a href="c-ch64.htm#92861">Ns_ConnContentLength</a></p>
<td><p><a name="38251">
</a>Return content length </p>

<tr><td><p><a name="574403">
</a><a href="c-ch65.htm#213972">Ns_ConnContentSent</a></p>
<td><p><a name="574405">
</a>Check if browser sent content</p>

<tr><td><p><a name="574423">
</a><a href="c-ch66.htm#574868">Ns_ConnCopyToChannel</a></p>
<td><p><a name="574425">
</a>Copy content to Tcl channel</p>

<tr><td><p><a name="38253">
</a><a href="c-ch67.htm#213954">Ns_ConnCopyToDString</a></p>
<td><p><a name="38255">
</a>Copy data from connection to dynamic string </p>

<tr><td><p><a name="574439">
</a><a href="c-ch68.htm#575198">Ns_ConnCopyToFd</a></p>
<td><p><a name="574441">
</a>Copy content to file descriptor</p>

<tr><td><p><a name="38257">
</a><a href="c-ch69.htm#93723">Ns_ConnCopyToFile</a></p>
<td><p><a name="38259">
</a>Copy data from connection to a file </p>

<tr><td><p><a name="38261">
</a><a href="c-ch70.htm#94151">Ns_ConnDriverContext</a></p>
<td><p><a name="38263">
</a>Return driver context </p>

<tr><td><p><a name="38265">
</a><a href="c-ch71.htm#94577">Ns_ConnDriverName</a></p>
<td><p><a name="38267">
</a>Return driver name </p>

<tr><td><p><a name="574455">
</a><a href="c-ch72.htm#575491">Ns_ConnFlushContent</a></p>
<td><p><a name="574457">
</a>Flush remaining content</p>

<tr><td><p><a name="38269">
</a><a href="c-ch74.htm#95419">Ns_ConnGetQuery</a></p>
<td><p><a name="38271">
</a>Construct Ns_Set representing query data </p>

<tr><td><p><a name="38273">
</a><a href="c-ch75.htm#95835">Ns_ConnGets</a></p>
<td><p><a name="38275">
</a>Read content into a buffer </p>

<tr><td><p><a name="38277">
</a><a href="c-ch76.htm#96249">Ns_ConnHeaders</a></p>
<td><p><a name="38279">
</a>Return headers </p>

<tr><td><p><a name="38281">
</a><a href="c-ch77.htm#96661">Ns_ConnHost</a></p>
<td><p><a name="38283">
</a>Return host </p>

<tr><td><p><a name="574474">
</a><a href="c-ch78.htm#575791">Ns_ConnInit</a></p>
<td><p><a name="574476">
</a>Run socket init procedure</p>

<tr><td><p><a name="38285">
</a><a href="c-ch79.htm#97071">Ns_ConnLocation</a></p>
<td><p><a name="38287">
</a>Return location </p>

<tr><td><p><a name="38289">
</a><a href="c-ch80.htm#97479">Ns_ConnModifiedSince</a></p>
<td><p><a name="38291">
</a>Determine if content modified since a specified date </p>

<tr><td><p><a name="38293">
</a><a href="c-ch82.htm#148180">Ns_ConnPeer</a></p>
<td><p><a name="38295">
</a>Return name of peer </p>

<tr><td><p><a name="574478">
</a><a href="c-ch83.htm#576075">Ns_ConnPeerPort</a></p>
<td><p><a name="574480">
</a>Return peer port</p>

<tr><td><p><a name="38297">
</a><a href="c-ch84.htm#98302">Ns_ConnPort</a></p>
<td><p><a name="38299">
</a>Return port </p>

<tr><td><p><a name="38301">
</a><a href="c-ch86.htm#99104">Ns_ConnPuts</a></p>
<td><p><a name="38303">
</a>Send a string to a client </p>

<tr><td><p><a name="38305">
</a><a href="c-ch87.htm#99502">Ns_ConnRead</a></p>
<td><p><a name="38307">
</a>Read content into buffer </p>

<tr><td><p><a name="574482">
</a><a href="c-ch88.htm#576367">Ns_ConnReadHeaders</a></p>
<td><p><a name="574484">
</a>Read headers into Ns_Set</p>

<tr><td><p><a name="38309">
</a><a href="c-ch89.htm#99898">Ns_ConnReadLine</a></p>
<td><p><a name="38311">
</a>Read a line from a connection </p>

<tr><td><p><a name="574486">
</a><a href="c-ch90.htm#576649">Ns_ConnRedirect</a></p>
<td><p><a name="574488">
</a>Perform internal redirect</p>

<tr><td><p><a name="38313">
</a><a href="c-ch92.htm#100684">Ns_ConnResponseLength</a></p>
<td><p><a name="38315">
</a>Return response length </p>

<tr><td><p><a name="38317">
</a><a href="c-ch93.htm#101074">Ns_ConnResponseStatus</a></p>
<td><p><a name="38319">
</a>Return response status </p>

<tr><td><p><a name="574533">
</a><a href="c-ch107.htm#582304">Ns_ConnReturnOpenChannel</a></p>
<td><p><a name="574535">
</a>Write Tcl channel content to conn</p>

<tr><td><p><a name="574569">
</a><a href="c-ch114.htm#582597">Ns_ConnSendChannel</a></p>
<td><p><a name="574571">
</a>Send Tcl channel content to conn</p>

<tr><td><p><a name="788865">
</a>Ns_ConnSendDString</p>
<td><p><a name="788867">
</a>Write a DString to the conn</p>

<tr><td><p><a name="38321">
</a><a href="c-ch116.htm#60723">Ns_ConnSendFd</a></p>
<td><p><a name="38323">
</a>Write file to connection content </p>

<tr><td><p><a name="38325">
</a><a href="c-ch117.htm#60733">Ns_ConnSendFp</a></p>
<td><p><a name="38327">
</a>Write file to connection content </p>

<tr><td><p><a name="38329">
</a><a href="c-ch118.htm#104598">Ns_ConnServer</a></p>
<td><p><a name="38331">
</a>Return name of server </p>

<tr><td><p><a name="38337">
</a><a href="c-ch125.htm#107470">Ns_ConnWrite</a></p>
<td><p><a name="38339">
</a>Send data to a client </p>

<tr><td><p><a name="584936">
</a><a href="c-ch168.htm#584911">Ns_DriverEnableKeepalive</a></p>
<td><p><a name="584938">
</a>Enable HTTP Keepalive on driver</p>

<tr><td><p><a name="788892">
</a><a href="c-ch436.htm#790715">Ns_WriteConn</a></p>
<td><p><a name="788894">
</a>Send a specified length of data to the client</p>


</Table></p>
<a name="34402">
</a><h4>Logging Functions</h4>
<p><a name="36792">
</a>The functions in this category are listed in the following table.<Table Border = "3">
<tr><td><p><a name="38107">
</a><a href="c-ch189.htm#122352">Ns_Fatal</a></p>
<td><p><a name="38109">
</a>Log a fatal error and shutdown </p>

<tr><td><p><a name="38111">
</a><a href="c-ch244.htm#124634">Ns_Log</a></p>
<td><p><a name="38113">
</a>Log formatted message </p>

<tr><td><p><a name="591193">
</a><a href="c-ch245.htm#591214">Ns_LogRoll</a></p>
<td><p><a name="591195">
</a>Roll server log</p>

<tr><td><p><a name="38119">
</a><a href="c-ch246.htm#125016">Ns_LogTime</a></p>
<td><p><a name="38121">
</a>Construct local date and time for log file </p>

<tr><td><p><a name="38123">
</a><a href="c-ch303.htm#127765">Ns_RollFile</a></p>
<td><p><a name="38125">
</a>Rename a file and increment its backup number </p>


</Table></p>
<a name="569484">
</a><h4>Memory Pool Functions</h4>
<p><a name="569596">
</a>The functions in this category are listed in the following table:<Table Border = "3">
<tr><td><p><a name="569624">
</a><a href="c-ch273.htm#569676">Ns_PoolAlloc</a></p>
<td><p><a name="569626">
</a>Allocate memory within a pool</p>

<tr><td><p><a name="569558">
</a><a href="c-ch274.htm#569677">Ns_PoolCreate</a></p>
<td><p><a name="569560">
</a>Create a new memory pool</p>

<tr><td><p><a name="569565">
</a><a href="c-ch275.htm#569678">Ns_PoolDestroy</a></p>
<td><p><a name="569567">
</a>Destroy a memory pool</p>

<tr><td><p><a name="569572">
</a><a href="c-ch276.htm#569679">Ns_PoolDump</a></p>
<td><p><a name="569574">
</a>Debug a memory pool</p>

<tr><td><p><a name="569579">
</a><a href="c-ch277.htm#569680">Ns_PoolFree</a></p>
<td><p><a name="569581">
</a>Free pool memory</p>

<tr><td><p><a name="569586">
</a><a href="c-ch278.htm#569681">Ns_PoolRealloc</a></p>
<td><p><a name="569588">
</a>Reallocate pool memory</p>

<tr><td><p><a name="569593">
</a><a href="c-ch279.htm#569682">Ns_PoolTrace</a></p>
<td><p><a name="569595">
</a>Trace a memory pool</p>

<tr><td><p><a name="757437">
</a><a href="c-ch402.htm#570949">Ns_ThreadFree</a></p>
<td><p><a name="757439">
</a>Free thread pool memory</p>

<tr><td><p><a name="757471">
</a><a href="c-ch406.htm#570953">Ns_ThreadMalloc</a></p>
<td><p><a name="757473">
</a>Allocate thread pool memory</p>

<tr><td><p><a name="757464">
</a><a href="c-ch407.htm#570954">Ns_ThreadPool</a></p>
<td><p><a name="757466">
</a>Get thread pool memory</p>

<tr><td><p><a name="757457">
</a><a href="c-ch408.htm#570955">Ns_ThreadRealloc</a></p>
<td><p><a name="757459">
</a>Realloc thread pool memory</p>


</Table></p>
<p><a name="569509">
</a></p>
<a name="34411">
</a><h4>Mime-Related Functions</h4>
<p><a name="36814">
</a>The functions in this category are listed in the following table.<Table Border = "3">
<tr><td><p><a name="587369">
</a><a href="c-ch203.htm#586916">Ns_GetMimeType</a></p>
<td><p><a name="587371">
</a>Get Mime type</p>


</Table></p>
<a name="615783">
</a><h4>Module Logging Realms Functions</h4>
<p><a name="615827">
</a>The functions in this category are listed in the following table.<Table Border = "3">
<tr><td><p><a name="615789">
</a><a href="c-ch250.htm#595725">Ns_ModLog</a></p>
<td><p><a name="615791">
</a>Log a message with a realm</p>

<tr><td><p><a name="616235">
</a><a href="c-ch251.htm#612364">Ns_ModLogGetThreshold</a></p>
<td><p><a name="616237">
</a>Get the severity of the logging threshold of a handle</p>

<tr><td><p><a name="615803">
</a><a href="c-ch252.htm#615498">Ns_ModLogLookupHandle</a></p>
<td><p><a name="615805">
</a>Obtain the handle of a given realm</p>

<tr><td><p><a name="615810">
</a><a href="c-ch253.htm#615511">Ns_ModLogLookupRealm</a></p>
<td><p><a name="615812">
</a>Obtain the realm from the handle</p>

<tr><td><p><a name="615817">
</a><a href="c-ch254.htm#771977">Ns_ModLogRedirect</a></p>
<td><p><a name="615819">
</a>Redirect logging of a realm to a file</p>

<tr><td><p><a name="616188">
</a><a href="c-ch255.htm#598945">Ns_ModLogRegister</a></p>
<td><p><a name="616190">
</a>Register a new realm</p>

<tr><td><p><a name="615824">
</a><a href="c-ch256.htm#598980">Ns_ModLogSetThreshold</a></p>
<td><p><a name="615826">
</a>Set the logging severity of a handle</p>


</Table></p>
<a name="288454">
</a><h4>Scheduled Procedures Functions</h4>
<p><a name="288455">
</a>These functions allow you to specify a procedure to be run daily, weekly, or at specified intervals<Table Border = "3">
<tr><th><p><a name="288458">
</a><b>Function</b></p>
<th><p><a name="288460">
</a><b>Description</b></p>

<tr><td><p><a name="288465">
</a><a href="c-ch309.htm#289803">Ns_ScheduleDaily</a></p>
<td><p><a name="288467">
</a>Schedule a procedure to run once a day</p>

<tr><td><p><a name="348936">
</a><a href="c-ch310.htm#127905">Ns_ScheduleProc</a></p>
<td><p><a name="348938">
</a>Schedule a procedure to run at specified intervals (simplified options)</p>

<tr><td><p><a name="288472">
</a><a href="c-ch311.htm#289902">Ns_ScheduleProcEx</a></p>
<td><p><a name="288474">
</a>Schedule a procedure to run at specified intervals (expanded options)</p>

<tr><td><p><a name="288479">
</a><a href="c-ch312.htm#289925">Ns_ScheduleWeekly</a></p>
<td><p><a name="288481">
</a>Schedule a procedure to run once a week</p>

<tr><td><p><a name="288486">
</a><a href="c-ch419.htm#290386">Ns_UnscheduleProc</a></p>
<td><p><a name="288488">
</a>Stop a scheduled procedure</p>


</Table></p>
<a name="288490">
</a><h4>Sockets Interface Functions</h4>
<p><a name="288503">
</a>The following functions are available for managing sockets.  Developers should consult a book on socket programming when using these functions, for example "Unix Network Programming" by W. Richard Stevens.<Table Border = "3">
<tr><th><p><a name="288493">
</a><b>Function</b></p>
<th><p><a name="288495">
</a><b>Description</b></p>

<tr><td><p><a name="573095">
</a><a href="c-ch15.htm#201348">Ns_BindSock</a></p>
<td><p><a name="573097">
</a>Bind a socket as root</p>

<tr><td><p><a name="586593">
</a><a href="c-ch206.htm#587162">Ns_GetSockAddr</a></p>
<td><p><a name="586595">
</a>Get socket driver address</p>

<tr><td><p><a name="301125">
</a><a href="c-ch359.htm#289239">Ns_SockAsyncConnect</a></p>
<td><p><a name="301127">
</a>Create a remote socket and return immediately</p>

<tr><td><p><a name="288500">
</a><a href="c-ch360.htm#305084">Ns_SockCallback</a></p>
<td><p><a name="288502">
</a>Register a socket callback function</p>

<tr><td><p><a name="788881">
</a><a href="c-ch361.htm#790779">Ns_SockCancelCallback</a></p>
<td><p><a name="788883">
</a>Remove a socket callback</p>

<tr><td><p><a name="301121">
</a><a href="c-ch362.htm#304346">Ns_SockConnect</a></p>
<td><p><a name="301123">
</a>Create a socket to remote host and port</p>

<tr><td><p><a name="301065">
</a><a href="c-ch363.htm#306195">Ns_SockListen</a></p>
<td><p><a name="301067">
</a>Create a socket on a specified address and port</p>

<tr><td><p><a name="620804">
</a><a href="c-ch364.htm#620814">Ns_SockListenCallback</a></p>
<td><p><a name="620806">
</a>Register a socket callback function and create socket</p>

<tr><td><p><a name="301165">
</a><a href="c-ch365.htm#305382">Ns_SockPipe</a></p>
<td><p><a name="301167">
</a>Return a pair of connected sockets</p>

<tr><td><p><a name="626073">
</a><a href="c-ch366.htm#626083">Ns_SockPortBound</a></p>
<td><p><a name="626075">
</a>Determine if port is bound</p>

<tr><td><p><a name="301138">
</a><a href="c-ch367.htm#305384">Ns_SockSetBlocking</a></p>
<td><p><a name="301140">
</a>Set a socket in blocking mode</p>

<tr><td><p><a name="301142">
</a><a href="c-ch368.htm#305385">Ns_SockSetNonBlocking</a></p>
<td><p><a name="301144">
</a>Set a socket in nonblocking mode</p>

<tr><td><p><a name="301053">
</a><a href="c-ch369.htm#131787">Ns_SockTimedConnect</a></p>
<td><p><a name="301055">
</a>Create a remote socket within a specified time</p>


</Table></p>
<a name="34419">
</a><h4>Socket Driver Interface Functions</h4>
<p><a name="757638">
</a>The functions in this category are listed in the following table:<Table Border = "3">
<tr><td><p><a name="757754">
</a><a href="c-ch196.htm#586631">Ns_GetDriver</a></p>
<td><p><a name="757756">
</a>Get socket driver</p>

<tr><td><p><a name="757747">
</a><a href="c-ch197.htm#586632">Ns_GetDriverContext</a></p>
<td><p><a name="757749">
</a>Get socket driver context</p>

<tr><td><p><a name="757740">
</a><a href="c-ch198.htm#586633">Ns_GetDriverLabel</a></p>
<td><p><a name="757742">
</a>Get socket driver label</p>

<tr><td><p><a name="757733">
</a><a href="c-ch199.htm#586634">Ns_GetDriverName</a></p>
<td><p><a name="757735">
</a>Get socket driver name</p>

<tr><td><p><a name="788873">
</a><a href="c-ch200.htm#587577">Ns_GetDriverProc</a></p>
<td><p><a name="788875">
</a>Get a communications driver procedure</p>

<tr><td><p><a name="757726">
</a><a href="c-ch201.htm#586635">Ns_GetFirstDriver</a></p>
<td><p><a name="757728">
</a>Get pointer to first socket driver</p>

<tr><td><p><a name="757719">
</a><a href="c-ch204.htm#586917">Ns_GetNextDriver</a></p>
<td><p><a name="757721">
</a>Get pointer to next socket driver</p>

<tr><td><p><a name="757824">
</a><a href="c-ch281.htm#617461">Ns_QueueConn</a></p>
<td><p><a name="757826">
</a>Make a queue a new conn</p>

<tr><td><p><a name="757817">
</a><a href="c-ch292.htm#618396">Ns_RegisterDriver</a></p>
<td><p><a name="757819">
</a>Register a socket driver</p>

<tr><td><p><a name="757810">
</a><a href="c-ch294.htm#570330">Ns_RegisterLocation</a></p>
<td><p><a name="757812">
</a>Register location for socket driver</p>

<tr><td><p><a name="757803">
</a><a href="c-ch325.htm#784978">Ns_SetDriverProc</a></p>
<td><p><a name="757805">
</a>Set socket driver callback</p>


</Table></p>
<a name="757634">
</a><h4>Storage and Retrieval Functions</h4>
<p><a name="36836">
</a>The functions in this category are listed in the following table. In rows where more than one function is listed, the preferred function is listed first.<Table Border = "3">
<tr><td><p><a name="37883">
</a><a href="c-ch317.htm#128829">Ns_ServerSpecificAlloc</a></p>
<td><p><a name="37885">
</a>Return unique integer to use in other functions </p>

<tr><td><p><a name="37887">
</a><a href="c-ch318.htm#128953">Ns_ServerSpecificDestroy</a></p>
<td><p><a name="37889">
</a>Delete server-specific data </p>

<tr><td><p><a name="37891">
</a><a href="c-ch319.htm#129075">Ns_ServerSpecificGet</a></p>
<td><p><a name="37893">
</a>Retrieve server-specific data </p>

<tr><td><p><a name="37895">
</a><a href="c-ch320.htm#129195">Ns_ServerSpecificSet</a></p>
<td><p><a name="37897">
</a>Store server-specific data for subsequent retrieval </p>

<tr><td><p><a name="758251">
</a><a href="c-ch413.htm#636997">Ns_TlsAlloc</a>, <a href="c-ch9.htm#879729">Ns_AllocThreadLocalStorage</a></p>
<td><p><a name="758253">
</a>Allocate thread local storage</p>

<tr><td><p><a name="758244">
</a><a href="c-ch414.htm#636998">Ns_TlsGet</a>, <a href="c-ch209.htm#65946">Ns_GetThreadLocalStorage</a></p>
<td><p><a name="758246">
</a>Get thread local storage</p>

<tr><td><p><a name="758237">
</a><a href="c-ch415.htm#636999">Ns_TlsSet</a>, <a href="c-ch348.htm#65821">Ns_SetThreadLocalStorage</a></p>
<td><p><a name="758239">
</a>Set thread local storage</p>

<tr><td><p><a name="37899">
</a><a href="c-ch422.htm#132065">Ns_UrlSpecificAlloc</a></p>
<td><p><a name="37901">
</a>Return unique integer to use in other functions </p>

<tr><td><p><a name="37903">
</a><a href="c-ch423.htm#132095">Ns_UrlSpecificDestroy</a></p>
<td><p><a name="37905">
</a>Delete URL-specific data </p>

<tr><td><p><a name="37907">
</a><a href="c-ch424.htm#132123">Ns_UrlSpecificGet</a></p>
<td><p><a name="37909">
</a>Retrieve URL-specific data </p>

<tr><td><p><a name="37911">
</a><a href="c-ch425.htm#214494">Ns_UrlSpecificGetExact</a></p>
<td><p><a name="37913">
</a>Retrieve URL-specific data without inheritance </p>

<tr><td><p><a name="37915">
</a><a href="c-ch426.htm#132173">Ns_UrlSpecificSet</a></p>
<td><p><a name="37917">
</a>Store URL-specific data for subsequent retrieval </p>


</Table> </p>
<a name="700157">
</a><h4>Synchronization Functions</h4>
<a name="708743">
</a><h4>Condition Variables</h4>
<p><a name="708808">
</a>Condition variables are managed with the following functions<Table Border = "3">
<tr><td><p><a name="708770">
</a><a href="c-ch45.htm#551012">Ns_CondBroadcast</a></p>
<td><p><a name="708772">
</a>Wake up all threads waiting on a cond</p>

<tr><td><p><a name="708777">
</a><a href="c-ch46.htm#551013">Ns_CondDestroy</a></p>
<td><p><a name="708779">
</a>Free a cond's memory</p>

<tr><td><p><a name="708784">
</a><a href="c-ch47.htm#551014">Ns_CondInit</a></p>
<td><p><a name="708786">
</a>Initialize a cond</p>

<tr><td><p><a name="708791">
</a><a href="c-ch48.htm#551015">Ns_CondSignal</a></p>
<td><p><a name="708793">
</a>Wake up a single thread</p>

<tr><td><p><a name="708798">
</a><a href="c-ch49.htm#551016">Ns_CondTimedWait</a></p>
<td><p><a name="708800">
</a>Block on a cond</p>

<tr><td><p><a name="708805">
</a><a href="c-ch50.htm#551017">Ns_CondWait</a></p>
<td><p><a name="708807">
</a>Wait indefinitely on a cond</p>


</Table></p>
<a name="708744">
</a><h4>Semaphores</h4>
<p><a name="708821">
</a>Semaphores are managed with the following functions. The preferred function is listed first in each row.<Table Border = "3">
<tr><td><p><a name="717830">
</a><a href="c-ch313.htm#619070">Ns_SemaDestroy</a>, <a href="c-ch166.htm#69621">Ns_DestroySemaphore</a></p>
<td><p><a name="717832">
</a>Destroy a semaphore object</p>

<tr><td><p><a name="717837">
</a><a href="c-ch314.htm#619071">Ns_SemaInit</a>, <a href="c-ch239.htm#424833">Ns_InitializeSemaphore</a></p>
<td><p><a name="717839">
</a>Initialize a semaphore object</p>

<tr><td><p><a name="717844">
</a><a href="c-ch315.htm#619072">Ns_SemaPost</a>, <a href="c-ch302.htm#232203">Ns_ReleaseSemaphore</a></p>
<td><p><a name="717846">
</a>Increment a semaphore object</p>

<tr><td><p><a name="717851">
</a><a href="c-ch316.htm#619073">Ns_SemaWait</a>, <a href="c-ch431.htm#214172">Ns_WaitForSemaphore</a></p>
<td><p><a name="717853">
</a>Wait for a semaphore object to be incremented above 0.</p>


</Table></p>
<a name="708745">
</a><h4>Mutexes</h4>
<p><a name="708926">
</a>Mutexes are managed with the following functions. The preferred function is listed first in each row.<Table Border = "3">
<tr><td><p><a name="726662">
</a><a href="c-ch260.htm#616329">Ns_MutexDestroy</a>, <a href="c-ch164.htm#68530">Ns_DestroyMutex</a></p>
<td><p><a name="726664">
</a>Destroy a mutex object</p>

<tr><td><p><a name="726669">
</a><a href="c-ch261.htm#616330">Ns_MutexInit</a>, <a href="c-ch237.htm#68238">Ns_InitializeMutex</a></p>
<td><p><a name="726671">
</a>Initialize a mutex object</p>

<tr><td><p><a name="726676">
</a><a href="c-ch262.htm#616331">Ns_MutexLock</a>, <a href="c-ch243.htm#68947">Ns_LockMutex</a></p>
<td><p><a name="726678">
</a>Lock a mutext object</p>

<tr><td><p><a name="726683">
</a><a href="c-ch263.htm#616332">Ns_MutexUnlock</a>, <a href="c-ch416.htm#69431">Ns_UnlockMutex</a></p>
<td><p><a name="726685">
</a>Unlock a mutext object</p>


</Table></p>
<a name="708746">
</a><h4>Events</h4>
<p><a name="708948">
</a>Events are managed with the following functions:<Table Border = "3">
<tr><td><p><a name="757903">
</a><a href="c-ch6.htm#572450">Ns_AbsTimedWaitForEvent</a></p>
<td><p><a name="757905">
</a>Wait for an event to be broadcast</p>

<tr><td><p><a name="757958">
</a><a href="c-ch16.htm#70782">Ns_BroadcastEvent</a> </p>
<td><p><a name="757960">
</a>Wake all threads blocked in Ns_WaitForEvent.</p>

<tr><td><p><a name="757918">
</a><a href="c-ch163.htm#70334">Ns_DestroyEvent</a> </p>
<td><p><a name="757920">
</a>Destory an event object.</p>

<tr><td><p><a name="757925">
</a><a href="c-ch236.htm#70175">Ns_InitializeEvent</a> </p>
<td><p><a name="757927">
</a>Initialize an event object.</p>

<tr><td><p><a name="757932">
</a><a href="c-ch326.htm#86033">Ns_SetEvent</a> </p>
<td><p><a name="757934">
</a>Wait no more than one thread blocked in Ns_WaitForEvent</p>

<tr><td><p><a name="757939">
</a><a href="c-ch412.htm#215461">Ns_TimedWaitForEvent</a> </p>
<td><p><a name="757941">
</a>Wait for an event to be raised or a timeout.</p>

<tr><td><p><a name="788524">
</a><a href="c-ch428.htm#788478">Ns_UTimedWaitForEvent</a></p>
<td><p><a name="788526">
</a>Wait for an event for a specified time, in microseconds</p>

<tr><td><p><a name="788531">
</a><a href="c-ch429.htm#71864">Ns_WaitForEvent</a> </p>
<td><p><a name="788533">
</a>Wait for an event to be raised.</p>


</Table></p>
<a name="708747">
</a><h4>Critical Sections</h4>
<p><a name="709239">
</a>Critical sections are managed with the following functions. The preferred function is listed first in each row.<Table Border = "3">
<tr><td><p><a name="744441">
</a><a href="c-ch126.htm#582897">Ns_CsDestroy</a>, <a href="c-ch162.htm#67632">Ns_DestroyCriticalSection</a></p>
<td><p><a name="744443">
</a>Destroy a critical section object</p>

<tr><td><p><a name="744448">
</a><a href="c-ch127.htm#582898">Ns_CsEnter</a>, <a href="c-ch183.htm#66904">Ns_EnterCriticalSection</a></p>
<td><p><a name="744450">
</a>Enter a critical section of code</p>

<tr><td><p><a name="744455">
</a><a href="c-ch128.htm#582899">Ns_CsInit</a>, <a href="c-ch235.htm#66245">Ns_InitializeCriticalSection</a></p>
<td><p><a name="744457">
</a>Initialize a critical section object</p>

<tr><td><p><a name="744462">
</a><a href="c-ch129.htm#582900">Ns_CsLeave</a>, <a href="c-ch240.htm#67405">Ns_LeaveCriticalSection</a></p>
<td><p><a name="744464">
</a>Leave a critical section of code</p>


</Table></p>
<a name="708752">
</a><h4>Read/write Locks</h4>
<p><a name="709254">
</a>Read/write locks are managed with the following functions. The preferred function is listed first in each row.<Table Border = "3">
<tr><td><p><a name="753321">
</a><a href="c-ch304.htm#618634">Ns_RWLockDestroy</a>, <a href="c-ch165.htm#424849">Ns_DestroyRWLock</a></p>
<td><p><a name="753323">
</a>Destroy a read/write lock</p>

<tr><td><p><a name="753328">
</a><a href="c-ch305.htm#618635">Ns_RWLockInit</a>, <a href="c-ch238.htm#424435">Ns_InitializeRWLock</a></p>
<td><p><a name="753330">
</a>Initialize a read/write lock</p>

<tr><td><p><a name="753335">
</a><a href="c-ch306.htm#618636">Ns_RWLockRdLock</a>, <a href="c-ch285.htm#427589">Ns_ReadLockRWLock</a></p>
<td><p><a name="753337">
</a>Acquire a read lock</p>

<tr><td><p><a name="753342">
</a><a href="c-ch307.htm#618637">Ns_RWLockUnlock</a>, <a href="c-ch286.htm#427772">Ns_ReadUnlockRWLock</a>, <a href="c-ch438.htm#428028">Ns_WriteUnlockRWLock</a></p>
<td><p><a name="753344">
</a>Release a read/write lock</p>

<tr><td><p><a name="753349">
</a><a href="c-ch308.htm#618638">Ns_RWLockWrLock</a>, <a href="c-ch437.htm#427997">Ns_WriteLockRWLock</a></p>
<td><p><a name="753351">
</a>Acquire a write lock</p>


</Table></p>
<a name="34428">
</a><h4>Thread Interface Functions</h4>
<p><a name="34432">
</a>The following functions are used to support platform independent multithreaded programming. A table following this list of functions points you to further information for each function.<Table Border = "3">
<tr><td><p><a name="573413">
</a><a href="c-ch43.htm#573428">Ns_CheckStack</a></p>
<td><p><a name="573415">
</a>Check for thread stack overflow</p>

<tr><td><p><a name="586277">
</a><a href="c-ch192.htm#586283">Ns_Fork</a></p>
<td><p><a name="586279">
</a>Perform a fork</p>

<tr><td><p><a name="37774">
</a><a href="c-ch207.htm#65425">Ns_GetThread</a> </p>
<td><p><a name="184111">
</a>Get the thread object of the current thread.</p>

<tr><td><p><a name="37776">
</a><a href="c-ch208.htm#65432">Ns_GetThreadId</a> </p>
<td><p><a name="184113">
</a>Get a unique integer ID for the current thread.</p>

<tr><td><p><a name="570540">
</a><a href="c-ch400.htm#570947">Ns_ThreadCreate</a>, <a href="c-ch14.htm#201235">Ns_BeginThread</a>, <a href="c-ch13.htm#65191">Ns_BeginDetachedThread</a></p>
<td><p><a name="570542">
</a>Create new thread</p>

<tr><td><p><a name="570544">
</a><a href="c-ch401.htm#570948">Ns_ThreadExit</a>, <a href="c-ch188.htm#586004">Ns_ExitThread</a></p>
<td><p><a name="570546">
</a>Free or exit thread</p>

<tr><td><p><a name="570552">
</a><a href="c-ch403.htm#571591">Ns_ThreadGetName</a></p>
<td><p><a name="570554">
</a>Get thread name</p>

<tr><td><p><a name="570556">
</a><a href="c-ch404.htm#570951">Ns_ThreadId</a></p>
<td><p><a name="570558">
</a>Get thread ID</p>

<tr><td><p><a name="570560">
</a><a href="c-ch405.htm#570952">Ns_ThreadJoin</a>, <a href="c-ch435.htm#637361">Ns_WaitThread</a>, <a href="c-ch433.htm#214118">Ns_WaitForThread</a></p>
<td><p><a name="570562">
</a>Wait for thread exit</p>

<tr><td><p><a name="570576">
</a><a href="c-ch409.htm#570956">Ns_ThreadSelf</a></p>
<td><p><a name="570578">
</a>Get handle to thread</p>

<tr><td><p><a name="570580">
</a><a href="c-ch410.htm#570957">Ns_ThreadSetname</a></p>
<td><p><a name="570582">
</a>Set thread name</p>

<tr><td><p><a name="37804">
</a><a href="c-ch411.htm#65664">Ns_ThreadYield</a> </p>
<td><p><a name="184141">
</a>Put the current thread to sleep momentarily, allowing other threads to run,</p>

<tr><td><p><a name="627043">
</a><a href="c-ch430.htm#637218">Ns_WaitForProcess</a></p>
<td><p><a name="627045">
</a>Wait for process to exit</p>

<tr><td><p><a name="627051">
</a><a href="c-ch432.htm#637285">Ns_WaitForStartup</a></p>
<td><p><a name="627053">
</a>Block until server startup</p>

<tr><td><p><a name="627398">
</a><a href="c-ch434.htm#637340">Ns_WaitProcess</a></p>
<td><p><a name="627400">
</a>Wait for process to exit</p>


</Table></p>
<p><a name="288716">
</a>The following table tells you what to look under in your vendor-specific documentation for more information on threaded programming with respect to each function.<Table Border = "3">
<tr><th><p><a name="758587">
</a><b>Function</b></p>
<th><p><a name="758590">
</a><b>Solaris</b></p>
<th><p><a name="758593">
</a><b>pthread</b></p>
<th><p><a name="758596">
</a><b>SGI sproc</b> (2)</p>

<tr><td><p><a name="758598">
</a><b>Threads:</b></p>
<td><p><a name="758600">
</a></p>
<td><p><a name="758602">
</a></p>
<td><p><a name="758604">
</a></p>

<tr><td><p><a name="758606">
</a>Ns_ThreadCreate</p>
<td><p><a name="758608">
</a>thr_create</p>
<td><p><a name="758610">
</a>pthread_create</p>
<td><p><a name="758612">
</a>sproc (4)</p>

<tr><td><p><a name="758614">
</a>Ns_ThreadJoin</p>
<td><p><a name="758616">
</a>thr_join</p>
<td><p><a name="758618">
</a>pthread_join (3)</p>
<td><p><a name="758620">
</a>waitpid</p>

<tr><td><p><a name="758622">
</a>Ns_GetThreadId</p>
<td><p><a name="758624">
</a>thr_self</p>
<td><p><a name="758626">
</a>pthread_self</p>
<td><p><a name="758628">
</a>getpid</p>

<tr><td><p><a name="758630">
</a><b>Mutexes:</b></p>
<td><p><a name="758632">
</a></p>
<td><p><a name="758634">
</a></p>
<td><p><a name="758636">
</a></p>

<tr><td><p><a name="758638">
</a>Ns_MutexInit</p>
<td><p><a name="758640">
</a>mutex_int</p>
<td><p><a name="758642">
</a>pthread_mutex_init</p>
<td><p><a name="758644">
</a>usnewlock</p>

<tr><td><p><a name="758646">
</a>Ns_MutexDestroy</p>
<td><p><a name="758648">
</a>mutex_destroy</p>
<td><p><a name="758650">
</a>pthread_mutex_des-troy</p>
<td><p><a name="758652">
</a>usfreelock</p>

<tr><td><p><a name="758654">
</a>Ns_MutexLock</p>
<td><p><a name="758656">
</a>mutex_lock</p>
<td><p><a name="758658">
</a>pthread_mutex_lock</p>
<td><p><a name="758660">
</a>ussetlock</p>

<tr><td><p><a name="758662">
</a>Ns_MutexUnlock</p>
<td><p><a name="758664">
</a>mutex_unlock</p>
<td><p><a name="758666">
</a>pthread_mutex_un-lock</p>
<td><p><a name="758668">
</a>usunsetlock</p>

<tr><td><p><a name="758670">
</a><b>Semaphores:</b></p>
<td><p><a name="758672">
</a></p>
<td><p><a name="758674">
</a></p>
<td><p><a name="758676">
</a></p>

<tr><td><p><a name="758678">
</a>Ns_SemaInit</p>
<td><p><a name="758680">
</a>sema_int</p>
<td><p><a name="758682">
</a>(5)</p>
<td><p><a name="758684">
</a>usnewsema</p>

<tr><td><p><a name="758686">
</a>Ns_SemaDestroy</p>
<td><p><a name="758688">
</a>sema_destroy</p>
<td><p><a name="758690">
</a>(5)</p>
<td><p><a name="758692">
</a>usfreesema</p>

<tr><td><p><a name="758694">
</a>Ns_SemaWait</p>
<td><p><a name="758696">
</a>sema_wait</p>
<td><p><a name="758698">
</a>(5)</p>
<td><p><a name="758700">
</a>uspsema</p>

<tr><td><p><a name="758702">
</a>Ns_SemaPost</p>
<td><p><a name="758704">
</a>sema_post</p>
<td><p><a name="758706">
</a>(5)</p>
<td><p><a name="758708">
</a>usvsema</p>

<tr><td><p><a name="758710">
</a><b>Events:</b></p>
<td><p><a name="758712">
</a></p>
<td><p><a name="758714">
</a></p>
<td><p><a name="758716">
</a></p>

<tr><td><p><a name="758718">
</a>Ns_InitializeEvent</p>
<td><p><a name="758720">
</a>cond_int</p>
<td><p><a name="758722">
</a>pthread_cond_init</p>
<td><p><a name="758724">
</a>(6)</p>

<tr><td><p><a name="758726">
</a>Ns_DestroyEvent</p>
<td><p><a name="758728">
</a>cond_destroy</p>
<td><p><a name="758730">
</a>pthread_cond_destroy</p>
<td><p><a name="758732">
</a>(6)</p>

<tr><td><p><a name="758734">
</a>Ns_WaitForEvent</p>
<td><p><a name="758736">
</a>cond_wait</p>
<td><p><a name="758738">
</a>pthread_cond_wait</p>
<td><p><a name="758740">
</a>sigtimedwait</p>

<tr><td><p><a name="758742">
</a>Ns_TimedWaitForEvent</p>
<td><p><a name="758744">
</a>cond_timedwait</p>
<td><p><a name="758746">
</a>pthread_cond_timed-wait</p>
<td><p><a name="758748">
</a>sigtimedwait</p>

<tr><td><p><a name="758750">
</a>Ns_SetEvent</p>
<td><p><a name="758752">
</a>cond_signal</p>
<td><p><a name="758754">
</a>pthread_cond_signal</p>
<td><p><a name="758756">
</a>kill</p>

<tr><td><p><a name="758758">
</a>Ns_BroadcastEvent</p>
<td><p><a name="758760">
</a>cond_broadcast</p>
<td><p><a name="758762">
</a>pthread_cond_broad-cast</p>
<td><p><a name="758764">
</a>kill</p>

<tr><td><p><a name="758766">
</a><b>Critical Sections:</b></p>
<td><p><a name="758768">
</a></p>
<td><p><a name="758770">
</a></p>
<td><p><a name="758772">
</a></p>

<tr><td><p><a name="758774">
</a>Ns_CsInit</p>
<td><p><a name="758776">
</a>(10)</p>
<td><p><a name="758778">
</a>pthread_mutex_init (10)</p>
<td><p><a name="758780">
</a>(10)</p>

<tr><td><p><a name="758782">
</a>Ns_CsDestroy</p>
<td><p><a name="758784">
</a>(10)</p>
<td><p><a name="758786">
</a>pthread_mutex_de-stroy</p>
<td><p><a name="758788">
</a>(10)</p>

<tr><td><p><a name="758790">
</a>Ns_CsEnter</p>
<td><p><a name="758792">
</a>(10)</p>
<td><p><a name="758794">
</a>pthread_mutex_lock</p>
<td><p><a name="758796">
</a>(10)</p>

<tr><td><p><a name="758798">
</a>Ns_CsLeave</p>
<td><p><a name="758800">
</a>(10)</p>
<td><p><a name="758802">
</a>pthread_mutex_un-lock</p>
<td><p><a name="758804">
</a>(10)</p>

<tr><td><p><a name="758806">
</a>Ns_TlsAlloc</p>
<td><p><a name="758808">
</a>thr_keycreate</p>
<td><p><a name="758810">
</a>pthread_keycreate</p>
<td><p><a name="758812">
</a>(11)</p>

<tr><td><p><a name="758814">
</a>Ns_TlsSet</p>
<td><p><a name="758816">
</a>thr_setspecific</p>
<td><p><a name="758818">
</a>pthread_setspecific</p>
<td><p><a name="758820">
</a>(11)</p>

<tr><td><p><a name="758822">
</a>Ns_TlsGet</p>
<td><p><a name="758824">
</a>thr_getspecific</p>
<td><p><a name="758826">
</a>pthread_getspecific</p>
<td><p><a name="758828">
</a>(11)</p>


</Table></p>
<a name="289018">
</a><h4>Notes:</h4>
<p><a name="289020">
</a>(2) Threads on SGI Irix 5.3 are implemented as a process group with all attributes shared.  As such, threads will show up as separate processes in a process listing using the ps command.  Note, however, that although the server is implemented with multiple processes, it is still multithreaded in all respects (e.g., a single address space, open file table, etc.).  In addition, if one process dies unexpectantly (e.g., core dump or on receiving a kill -9), the other processes will be notified and immediately exit. On Irix 6.2, you may run the 5.3 share group version (nsd binary) or a newer pthreads interface binary (nsdp). </p>
<p><a name="289021">
</a>(3) The pthread_join routine would allow multiple threads to wait for a single thread to exit on pthreads.  However, in the nsthread library, only a single thread may wait using the Ns_ThreadJoin function. </p>
<p><a name="289022">
</a>(4) To allow any thread to wait for any other thread as in other multithreaded platforms, the SGI Irix threads interface uses a thread manager process which actually performs the sproc and waitpid calls on behalf of the other process threads.</p>
<p><a name="289023">
</a>(5) Pthreads does not include a semaphore and is emulated with a mutex and condition variable.</p>
<p><a name="289024">
</a>(6) SGI Irix does not include an event object and is emulated with ordinary process signals and the sigtimedwait and kill system calls.</p>
<p><a name="289025">
</a>(7) Nsthread events are emulated with pthread condition variables.</p>
<p><a name="289028">
</a>(10) Critical sections are emulated with a mutex and a condition variable. </p>
<p><a name="289029">
</a>(11) Thread local storage is not available on SGI sproc and is emulated using the PRDA, the process data area, as defined in the sys/prcnt.h header.</p>
<a name="371209">
</a><h4>Tcl Interpreter Functions</h4>
<p><a name="371418">
</a>The following functions are used to manipulate Tcl interpreters.<Table Border = "3">
<tr><td><p><a name="371230">
</a><a href="c-ch195.htm#377481">Ns_GetConnInterp</a></p>
<td><p><a name="371232">
</a>Get the Tcl interpreter for the connection</p>

<tr><td><p><a name="371237">
</a><a href="c-ch380.htm#377678">Ns_TclAllocateInterp</a></p>
<td><p><a name="371239">
</a>Allocate a Tcl interpreter for a  server</p>

<tr><td><p><a name="767499">
</a><a href="c-ch382.htm#354376">Ns_TclDeAllocateInterp</a></p>
<td><p><a name="767501">
</a>Perform cleanup after deallocating a Tcl interpreter</p>

<tr><td><p><a name="626757">
</a><a href="c-ch383.htm#626769">Ns_TclDestroyInterp</a></p>
<td><p><a name="626759">
</a>Mark Tcl interpreter for deletion</p>

<tr><td><p><a name="626939">
</a><a href="c-ch392.htm#354432">Ns_TclInitInterps</a></p>
<td><p><a name="626941">
</a>Call a Tcl init procedure in the parent interpreter</p>

<tr><td><p><a name="626753">
</a><a href="c-ch394.htm#626848">Ns_TclInterpServer</a></p>
<td><p><a name="626755">
</a>Return name of server</p>

<tr><td><p><a name="767476">
</a><a href="c-ch397.htm#636578">Ns_TclMarkForDelete</a></p>
<td><p><a name="767478">
</a>Mark Tcl interpreter for deletion</p>


</Table></p>
<p><a name="371218">
</a></p>
<a name="34476">
</a><h4>Miscellaneous Functions</h4>
<p><a name="34480">
</a>The following are miscellaneous utility functions in the AOLserver C API.<Table Border = "3">
<tr><td><p><a name="789197">
</a><a href="c-ch7.htm#789293">Ns_AdjTime</a></p>
<td><p><a name="789199">
</a>Adjust Ns_Time</p>

<tr><td><p><a name="572767">
</a><a href="c-ch10.htm#184362">Ns_Asctime</a></p>
<td><p><a name="572769">
</a>Perform asctime_r</p>

<tr><td><p><a name="573765">
</a><a href="c-ch44.htm#573779">Ns_CloseOnExec</a></p>
<td><p><a name="573767">
</a>Set close-on-exec flag</p>

<tr><td><p><a name="583352">
</a><a href="c-ch130.htm#583360">Ns_Ctime</a></p>
<td><p><a name="583354">
</a>Perform ctime_r</p>

<tr><td><p><a name="584669">
</a><a href="c-ch167.htm#584675">Ns_DiffTime</a></p>
<td><p><a name="584671">
</a>Get difference between two times</p>

<tr><td><p><a name="332858">
</a><a href="c-ch180.htm#121866">Ns_DupHigh</a></p>
<td><p><a name="332860">
</a>Move file descriptors</p>

<tr><td><p><a name="37568">
</a><a href="c-ch182.htm#122110">Ns_Encrypt</a></p>
<td><p><a name="37570">
</a>Encrypt a password in the form used by the Unix /etc/passwd file and the nsperm module.</p>

<tr><td><p><a name="585228">
</a><a href="c-ch184.htm#585567">Ns_ExecArgblk</a></p>
<td><p><a name="585230">
</a>Execute file with argument string</p>

<tr><td><p><a name="585232">
</a><a href="c-ch185.htm#585568">Ns_ExecArgv</a></p>
<td><p><a name="585234">
</a>Execute file with argument array</p>

<tr><td><p><a name="585236">
</a><a href="c-ch186.htm#585569">Ns_ExecProc</a></p>
<td><p><a name="585238">
</a>Execute file with argument array</p>

<tr><td><p><a name="585240">
</a><a href="c-ch187.htm#585570">Ns_ExecProcess</a></p>
<td><p><a name="585242">
</a>Execute file with argument string</p>

<tr><td><p><a name="37572">
</a><a href="c-ch190.htm#122590">Ns_FetchPage</a></p>
<td><p><a name="37574">
</a>Copy data from URL to dynamic string </p>

<tr><td><p><a name="37576">
</a><a href="c-ch191.htm#122826">Ns_FetchURL</a></p>
<td><p><a name="37578">
</a>Fetch a remote URL. </p>

<tr><td><p><a name="37580">
</a><a href="c-ch202.htm#123750">Ns_GetHostByAddr</a></p>
<td><p><a name="37582">
</a>Convert an IP address to a hostname </p>

<tr><td><p><a name="587760">
</a><a href="c-ch210.htm#587805">Ns_GetTime</a></p>
<td><p><a name="587762">
</a>Perform gettimeofday</p>

<tr><td><p><a name="587764">
</a><a href="c-ch211.htm#587806">Ns_GetUid</a></p>
<td><p><a name="587766">
</a>Return UID of user</p>

<tr><td><p><a name="353906">
</a><a href="c-ch212.htm#353934">Ns_GetUserHome</a></p>
<td><p><a name="353908">
</a>Get Unix user's home directory</p>

<tr><td><p><a name="587777">
</a><a href="c-ch213.htm#588039">Ns_Gmtime</a></p>
<td><p><a name="587779">
</a>Perform gmtime</p>

<tr><td><p><a name="37584">
</a><a href="c-ch215.htm#124422">Ns_HttpTime</a></p>
<td><p><a name="37586">
</a>Return a formatted time string </p>

<tr><td><p><a name="587781">
</a><a href="c-ch216.htm#588232">Ns_HtuuDecode</a></p>
<td><p><a name="587783">
</a>Perform base64 decode</p>

<tr><td><p><a name="587785">
</a><a href="c-ch217.htm#588233">Ns_HtuuEncode</a></p>
<td><p><a name="587787">
</a>Perform base64 encode</p>

<tr><td><p><a name="587789">
</a><a href="c-ch218.htm#588470">Ns_IncrTime</a></p>
<td><p><a name="587791">
</a>Increment time by seconds and microseconds</p>

<tr><td><p><a name="587793">
</a><a href="c-ch219.htm#588472">Ns_InetNtoa</a></p>
<td><p><a name="587795">
</a>Perform inet_ntoa</p>

<tr><td><p><a name="589504">
</a><a href="c-ch220.htm#588963">Ns_InfoBootTime</a></p>
<td><p><a name="589506">
</a>Return server boot time</p>

<tr><td><p><a name="360846">
</a><a href="c-ch221.htm#360684">Ns_InfoBuildDate</a></p>
<td><p><a name="360848">
</a>Return AOLserver build date</p>

<tr><td><p><a name="37588">
</a><a href="c-ch222.htm#360834">Ns_InfoConfigFile</a></p>
<td><p><a name="37590">
</a>Return full path name of the configuration file in use.</p>

<tr><td><p><a name="589508">
</a><a href="c-ch223.htm#589790">Ns_InfoErrorLog</a></p>
<td><p><a name="589510">
</a>Return error log name</p>

<tr><td><p><a name="37592">
</a><a href="c-ch224.htm#40549">Ns_InfoHomePath</a></p>
<td><p><a name="37594">
</a>Return directory where the AOLserver is installed.</p>

<tr><td><p><a name="589512">
</a><a href="c-ch225.htm#590016">Ns_InfoHostname</a></p>
<td><p><a name="589514">
</a>Return hostname of server</p>

<tr><td><p><a name="848396">
</a><a href="c-ch226.htm#848209">Ns_InfoLabel</a></p>
<td><p><a name="848398">
</a>Return source code label of server</p>

<tr><td><p><a name="589516">
</a><a href="c-ch227.htm#590256">Ns_InfoPid</a></p>
<td><p><a name="589518">
</a>Return server pid</p>

<tr><td><p><a name="589520">
</a><a href="c-ch228.htm#590257">Ns_InfoPlatform</a></p>
<td><p><a name="589522">
</a>Return platform</p>

<tr><td><p><a name="37596">
</a><a href="c-ch229.htm#40550">Ns_InfoServerName</a></p>
<td><p><a name="37598">
</a>Return AOLserver name string ("AOLserver").</p>

<tr><td><p><a name="589527">
</a><a href="c-ch230.htm#590590">Ns_InfoServersStarted</a></p>
<td><p><a name="589529">
</a>Determine if server has started</p>

<tr><td><p><a name="37600">
</a><a href="c-ch231.htm#40551">Ns_InfoServerVersion</a></p>
<td><p><a name="37602">
</a>Return AOLserver version string.</p>

<tr><td><p><a name="590581">
</a><a href="c-ch232.htm#590820">Ns_InfoShutdownPending</a></p>
<td><p><a name="590583">
</a>Determine if a server shutdown is pending</p>

<tr><td><p><a name="589536">
</a><a href="c-ch233.htm#590821">Ns_InfoStarted</a></p>
<td><p><a name="589538">
</a>Determine if server has started</p>

<tr><td><p><a name="589540">
</a><a href="c-ch234.htm#590822">Ns_InfoUptime</a></p>
<td><p><a name="589542">
</a>Return time server has been running</p>

<tr><td><p><a name="591430">
</a><a href="c-ch241.htm#591666">Ns_LibPath</a></p>
<td><p><a name="591432">
</a>Construct path relative to lib</p>

<tr><td><p><a name="591434">
</a>Ns_Localtime</p>
<td><p><a name="591436">
</a>Perform localtime</p>

<tr><td><p><a name="592206">
</a><a href="c-ch249.htm#591990">Ns_Match</a></p>
<td><p><a name="592208">
</a>Compare two strings</p>

<tr><td><p><a name="37604">
</a><a href="c-ch257.htm#595729">Ns_ModuleLoad</a></p>
<td><p><a name="37606">
</a>Load a module into AOLserver </p>

<tr><td><p><a name="37608">
</a><a href="c-ch259.htm#125756">Ns_ModuleSymbol</a></p>
<td><p><a name="37610">
</a>Return symbol </p>

<tr><td><p><a name="616712">
</a><a href="c-ch264.htm#616718">Ns_NextWord</a></p>
<td><p><a name="616714">
</a>Find next word in string</p>

<tr><td><p><a name="37612">
</a><a href="c-ch266.htm#40568">Ns_PageRoot</a></p>
<td><p><a name="37614">
</a>Return path name of the AOLserver pages directory for a  server.</p>

<tr><td><p><a name="616941">
</a><a href="c-ch267.htm#616957">Ns_ParseHeader</a></p>
<td><p><a name="616943">
</a>Parse Http headers</p>

<tr><td><p><a name="616945">
</a><a href="c-ch268.htm#616958">Ns_ParseHttpTime</a></p>
<td><p><a name="616947">
</a>Convert Http time into time_t</p>

<tr><td><p><a name="789290">
</a><a href="c-ch270.htm#816654">Ns_ParseUrl</a></p>
<td><p><a name="789292">
</a>Parse a URL</p>

<tr><td><p><a name="37616">
</a><a href="c-ch282.htm#435651">Ns_QuoteHtml</a></p>
<td><p><a name="37618">
</a>Quote an HTML string </p>

<tr><td><p><a name="617693">
</a><a href="c-ch283.htm#617699">Ns_Readdir</a></p>
<td><p><a name="617695">
</a>Perform readdir</p>

<tr><td><p><a name="620480">
</a><a href="c-ch355.htm#620505">Ns_Sigmask</a></p>
<td><p><a name="620482">
</a>Perform sigprocmask</p>

<tr><td><p><a name="620484">
</a><a href="c-ch356.htm#620506">Ns_Signal</a></p>
<td><p><a name="620486">
</a>Install signal handler</p>

<tr><td><p><a name="620498">
</a><a href="c-ch357.htm#620636">Ns_Sigwait</a></p>
<td><p><a name="620500">
</a>Perform sigwait</p>

<tr><td><p><a name="626213">
</a><a href="c-ch370.htm#626230">Ns_StrCaseFind</a></p>
<td><p><a name="626215">
</a>Perform strstr</p>

<tr><td><p><a name="626336">
</a><a href="c-ch375.htm#626396">Ns_StrToLower</a></p>
<td><p><a name="626338">
</a>Lowercase string</p>

<tr><td><p><a name="626332">
</a><a href="c-ch376.htm#626397">Ns_StrToUpper</a></p>
<td><p><a name="626334">
</a>Uppercase string</p>

<tr><td><p><a name="626328">
</a><a href="c-ch377.htm#626398">Ns_StrTrim</a></p>
<td><p><a name="626330">
</a>Trim string</p>

<tr><td><p><a name="626324">
</a><a href="c-ch378.htm#626399">Ns_StrTrimLeft</a></p>
<td><p><a name="626326">
</a>Trim blanks from left</p>

<tr><td><p><a name="626320">
</a><a href="c-ch379.htm#626400">Ns_StrTrimRight</a></p>
<td><p><a name="626322">
</a>Trim blanks from right</p>

<tr><td><p><a name="626316">
</a><a href="c-ch373.htm#786297">Ns_StringPrint</a></p>
<td><p><a name="626318">
</a>Print string</p>

<tr><td><p><a name="626312">
</a><a href="c-ch374.htm#787537">Ns_Strtok</a></p>
<td><p><a name="626314">
</a>Perform strtok_r</p>

<tr><td><p><a name="288031">
</a><a href="c-ch385.htm#290233">Ns_TclEval</a></p>
<td><p><a name="288033">
</a>Execute a Tcl script</p>

<tr><td><p><a name="626979">
</a><a href="c-ch387.htm#636244">Ns_TclGetConn</a></p>
<td><p><a name="626981">
</a>Get connection</p>

<tr><td><p><a name="626975">
</a><a href="c-ch388.htm#636245">Ns_TclGetOpenChannel</a></p>
<td><p><a name="626977">
</a>Get open channel in interpreter</p>

<tr><td><p><a name="626971">
</a><a href="c-ch389.htm#636246">Ns_TclGetOpenFd</a></p>
<td><p><a name="626973">
</a>Get open file descriptor</p>

<tr><td><p><a name="626967">
</a><a href="c-ch393.htm#636482">Ns_TclInitModule</a></p>
<td><p><a name="626969">
</a>Source Tcl module before server startup</p>

<tr><td><p><a name="626963">
</a><a href="c-ch395.htm#636576">Ns_TclLibrary</a></p>
<td><p><a name="626965">
</a>Return private Tcl directory</p>

<tr><td><p><a name="626959">
</a><a href="c-ch396.htm#636577">Ns_TclLogError</a></p>
<td><p><a name="626961">
</a>Write errorInfo to the log file</p>

<tr><td><p><a name="626951">
</a><a href="c-ch381.htm#788414">Ns_TclAppendInt</a></p>
<td><p><a name="626953">
</a>Append integer to Tcl result</p>

<tr><td><p><a name="626947">
</a><a href="c-ch398.htm#636580">Ns_TclRegisterAtCreate</a></p>
<td><p><a name="626949">
</a>Register function for interpreter creation</p>

<tr><td><p><a name="626943">
</a><a href="c-ch399.htm#636581">Ns_TclRegisterDeferred</a></p>
<td><p><a name="626945">
</a>Register function for interpreter cleanup</p>


</Table></p>
<a name="37064">
</a><h4>Database Functions</h4>
<p><a name="37068">
</a>The AOLserver provides several functions for accessing the database. These include convenient routines for sending DML and DDL SQL statements or SQL statements that return rows from the database. (DML stands for Data Manipulation Language and includes SQL statements to insert, update, and delete data.  DDL stands for Data Definition Language and includes SQL statements to create tables and views.)</p>
<p><a name="438743">
</a>There are also powerful catalog functions that help you build custom responses based on the schema of the tables within the database. These functions are only available if the nsdb module is loaded.</p>
<p><a name="34537">
</a>The following groups of database functions are described in the following subsections.<Table Border = "3">
<tr><td><p><a name="34506">
</a><a href="c-ch3.htm#34539">Pool Functions</a></p>
<td><p><a name="34508">
</a>Functions used to obtain information about database pools and obtain handles to database pools.</p>

<tr><td><p><a name="34512">
</a><a href="c-ch3.htm#34552">SQL Query Functions</a></p>
<td><p><a name="34515">
</a>Functions used to send queries to the database and process the results</p>

<tr><td><p><a name="789209">
</a><a href="c-ch3.htm#789223">Stored Procedure Functions</a></p>
<td><p><a name="789211">
</a>Functions used to run stored procedures.</p>

<tr><td><p><a name="34533">
</a><a href="c-ch3.htm#34615">Miscellaneous Functions</a></p>
<td><p><a name="34536">
</a>Miscellaneous functions associated with the database.</p>


</Table></p>
<a name="34539">
</a><h4>Pool Functions</h4>
<p><a name="37157">
</a>The functions in this category are listed in the following table.<Table Border = "3">
<tr><td><p><a name="370659">
</a><a href="c-ch134.htm#370673">Ns_DbBouncePool</a></p>
<td><p><a name="370661">
</a>Mark all database handles stale</p>

<tr><td><p><a name="37515">
</a><a href="c-ch143.htm#381853">Ns_DbPoolAllowable</a></p>
<td><p><a name="37517">
</a>Determine if pool is available </p>

<tr><td><p><a name="583636">
</a><a href="c-ch144.htm#584155">Ns_DbPoolDefault</a></p>
<td><p><a name="583638">
</a>Get default pool</p>

<tr><td><p><a name="37519">
</a><a href="c-ch145.htm#114692">Ns_DbPoolDescription</a></p>
<td><p><a name="37521">
</a>Get pool description </p>

<tr><td><p><a name="37523">
</a><a href="c-ch146.htm#230438">Ns_DbPoolGetHandle</a></p>
<td><p><a name="37525">
</a>Get database handle from pool </p>

<tr><td><p><a name="37527">
</a><a href="c-ch147.htm#115298">Ns_DbPoolGetMultipleHandles</a></p>
<td><p><a name="37529">
</a>Get multiple database handles from pool </p>

<tr><td><p><a name="37531">
</a><a href="c-ch148.htm#115598">Ns_DbPoolList</a></p>
<td><p><a name="37533">
</a>Get a list of available pools for a server </p>

<tr><td><p><a name="37535">
</a><a href="c-ch149.htm#115896">Ns_DbPoolPutHandle</a></p>
<td><p><a name="37537">
</a>Release a database handle for a pool </p>

<tr><td><p><a name="419820">
</a>Ns_DbPoolTimedGetHandle</p>
<td><p><a name="419822">
</a>Get database handle from pool with timeout</p>

<tr><td><p><a name="419816">
</a>Ns_DbPoolTimedGetMultipleHandles</p>
<td><p><a name="419818">
</a>Get multiple database handles from pool with timeout</p>


</Table></p>
<a name="34552">
</a><h4>SQL Query Functions</h4>
<p><a name="34556">
</a>The AOLserver C Database API includes the following functions for sending queries to the database and processing the results. Rows are returned as Ns_Set structures described earlier.<Table Border = "3">
<tr><td><p><a name="37462">
</a><a href="c-ch131.htm#107820">Ns_Db0or1Row</a></p>
<td><p><a name="37464">
</a>Execute an SQL statement that must return &lt;= 1 row </p>

<tr><td><p><a name="37466">
</a><a href="c-ch132.htm#108168">Ns_Db1Row</a></p>
<td><p><a name="37468">
</a>Execute an SQL statement that must return one row </p>

<tr><td><p><a name="288534">
</a><a href="c-ch133.htm#289385">Ns_DbBindRow</a></p>
<td><p><a name="288536">
</a>Return an Ns_Set structure of columns returned by the previously-executed SQL command</p>

<tr><td><p><a name="37470">
</a><a href="c-ch135.htm#109200">Ns_DbCancel</a></p>
<td><p><a name="37472">
</a>Cancel an active SQL select statement </p>

<tr><td><p><a name="37474">
</a><a href="c-ch136.htm#111538">Ns_DbDML</a></p>
<td><p><a name="37476">
</a>Execute an SQL DML statement </p>

<tr><td><p><a name="288541">
</a><a href="c-ch139.htm#289503">Ns_DbExec</a></p>
<td><p><a name="288543">
</a>Execute an SQL command</p>

<tr><td><p><a name="37478">
</a><a href="c-ch140.htm#112188">Ns_DbFlush</a></p>
<td><p><a name="37480">
</a>Flush any waiting rows </p>

<tr><td><p><a name="37482">
</a><a href="c-ch141.htm#112826">Ns_DbGetRow</a></p>
<td><p><a name="37484">
</a>Fetch the next waiting row after an Ns_DbSelect </p>

<tr><td><p><a name="583611">
</a><a href="c-ch142.htm#77927">Ns_DbInterpretSqlFile</a></p>
<td><p><a name="583613">
</a>Parse DML statements and send to database</p>

<tr><td><p><a name="37486">
</a><a href="c-ch154.htm#117068">Ns_DbSelect</a></p>
<td><p><a name="37488">
</a>Send a row-generating query to the database </p>


</Table></p>
<a name="789223">
</a><h4>Stored Procedure Functions</h4>
<p><a name="789260">
</a>The following functions handle stored procedures.<Table Border = "3">
<tr><td><p><a name="789229">
</a><a href="c-ch156.htm#816875">Ns_DbSpExec</a></p>
<td><p><a name="789231">
</a>Run a stored procedure</p>

<tr><td><p><a name="789236">
</a><a href="c-ch157.htm#816876">Ns_DbSpGetParams</a></p>
<td><p><a name="789238">
</a>Get output parameters from stored procedure</p>

<tr><td><p><a name="789243">
</a><a href="c-ch158.htm#816877">Ns_DbSpReturnCode</a></p>
<td><p><a name="789245">
</a>Get return code from stored procedure</p>

<tr><td><p><a name="789250">
</a><a href="c-ch159.htm#816878">Ns_DbSpSetParam</a></p>
<td><p><a name="789252">
</a>Set input parameter for stored procedure</p>

<tr><td><p><a name="789257">
</a><a href="c-ch160.htm#816879">Ns_DbSpStart</a></p>
<td><p><a name="789259">
</a>Start execution of a stored procedure</p>


</Table></p>
<a name="34615">
</a><h4>Miscellaneous Functions</h4>
<p><a name="37261">
</a>The following functions provide additional ways to manipulate the database.<Table Border = "3">
<tr><td><p><a name="583604">
</a><a href="c-ch137.htm#583646">Ns_DbDriverDbType</a></p>
<td><p><a name="583606">
</a>Get database type</p>

<tr><td><p><a name="37286">
</a><a href="c-ch138.htm#111864">Ns_DbDriverName</a></p>
<td><p><a name="37288">
</a>Get driver for database </p>

<tr><td><p><a name="37302">
</a><a href="c-ch152.htm#116192">Ns_DbQuoteValue</a></p>
<td><p><a name="37304">
</a>Adds extra single quote to single quotes in string </p>

<tr><td><p><a name="37306">
</a><a href="c-ch153.htm#116486">Ns_DbRegisterDriver</a></p>
<td><p><a name="37308">
</a>Register database driver with the server </p>

<tr><td><p><a name="37314">
</a><a href="c-ch155.htm#117356">Ns_DbSetException</a></p>
<td><p><a name="37316">
</a>Set last error message for database </p>


</Table></p>


<TABLE BORDER="2" CELLPADDING="1" width="100%">
<TR><TD COLSPAN=3><P ALIGN=Center>
<IMG SRC="bluebult.gif">
<A HREF="#topofpage">
<FONT SIZE=-1>Top of Page</FONT></A>
<IMG SRC="bluebult.gif">
</TD></TR>
<TR><TD COLSPAN=3><P ALIGN=Center>
<A href="c-ch2.htm">
<IMG  BORDER="0" src=navbprev.gif alt="[ Previous ]"></A>
<A href=toc.htm>
<IMG  BORDER="0" src=navbhome.gif alt="[ Contents ]"></A>
<A href=master.htm>
<IMG  BORDER="0" src=navbhelp.gif alt="[ Index ]"></A>
<A href="c-ch4.htm">
<IMG  BORDER="0" src=navbnext.gif alt="[ Next ]"></A>
<BR align=center>
<FONT size=-1>Copyright &copy; 1998-99 America Online,
Inc.</FONT>
</TD></TR></TABLE></BODY></HTML><!--plsfield:end-->