Provided by: aolserver4-dev_4.5.1-18.1_amd64 bug

NAME

       Ns_DStringAppend,    Ns_DStringAppendArg,    Ns_DStringAppendElement,    Ns_DStringExport,
       Ns_DStringFree,  Ns_DStringInit,   Ns_DStringLength,   Ns_DStringNAppend,   Ns_DStringPop,
       Ns_DStringPrintf,  Ns_DStringPush,  Ns_DStringSetLength, Ns_DStringTrunc, Ns_DStringValue,
       Ns_DStringVarAppend - library procedures

SYNOPSIS

       #include "ns.h"

       char *
       Ns_DStringAppend(Ns_DString *dsPtr, char *string)

       char *
       Ns_DStringAppendArg(Ns_DString *dsPtr, char *string)

       char *
       Ns_DStringAppendElement(Ns_DString *dsPtr, char *string)

       char *
       Ns_DStringExport(Ns_DString *dsPtr)

       void
       Ns_DStringFree(Ns_DString *dsPtr)

       void
       Ns_DStringInit(Ns_DString *dsPtr)

       int
       Ns_DStringLength(Ns_DString *dsPtr)

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

       Ns_DString *
       Ns_DStringPop(void)

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

       void
       Ns_DStringPush(Ns_DString *dsPtr)

       void
       Ns_DStringSetLength(Ns_DString *dsPtr, int length)

       void
       Ns_DStringTrunc(Ns_DString *dsPtr, int length)

       char *
       Ns_DStringValue(Ns_DString *dsPtr)

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

DESCRIPTION

       These functions create, manipulate and destroy  Ns_DStrings.  Ns_DStrings  are  structures
       that  store strings and information about the string length. These dynamic strings grow as
       need to fit the strings placed in them or appended to them. If  the  Ns_DString  plus  the
       appended  string  are  larger  than the size of original string within the Ns_DString, for
       example, the Ns_DString will be automatically extended by allocating more memory to it.

       Many functions return string  pointers  that  point  directly  to  the  string  within  an
       Ns_DString structure. You must not free these returned string pointers with Ns_Free or any
       other freeing function, but must instead use Ns_DStringFree to free memory associated with
       the Ns_DString.

       Ns_DStringAppend(dsPtr, string)

              Append  the  specified  string  plus a terminating null character to the end of the
              Ns_DString. Returns the string associated with the current Ns_DString.

              The Ns_DString ds of the following code would contain "foo " and have a  length  of
              3:

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

       Ns_DStringAppendArg(dsPtr, string)

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

       Ns_DStringAppendElement(dsPtr, string)

              Append a list element to the current value of a dynamic string. The string argument
              is reformatted as a list element and added to the current value of the  Ns_DString.
              The return value is a pointer to the dynamic string's new value.

       Ns_DStringExport(dsPtr)

              Returns  the current Ns_DString string and leaves the Ns_DString in the initialized
              state. In this case, the string returned needs to be freed eventually with  Ns_Free
              because the string pointer returned is not a part of the Ns_DString any longer.

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

       Ns_DStringFree(dsPtr)

              Free any allocated memory used by an Ns_DString.

       Ns_DStringInit(dsPtr)

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

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

       Ns_DStringLength(dsPtr)

              Return  the  current  length  of  the  string  value  that  is  contained within an
              Ns_DString.

              Ns_DString ds;
              Ns_DStringInit(&ds);
              Ns_DStringAppend(&ds, "<html></html>");
              printf("len=%d0, Ns_DStringLength(&ds));
              /* finished with dstring */
              Ns_DStringFree(&ds);

       Ns_DStringNAppend(dsPtr, string, length)

              Append n-characters of string to Ns_DString dsPtr. The function appends a string up
              to  the  specified  number of characters, plus a terminating null character. Unlike
              the Tcl_DStringAppend function, which only works with string  data,  the  AOLserver
              Ns_DStringNAppend  function  can append binary data.  Returns the string associated
              with the current Ns_DString.

              The resulting Ns_DString in this example, ds would
              contain "foo " and have a length of 3:

              Ns_DString ds;
              Ns_DStringInit(&ds);
              Ns_DStringNAppend(&ds, "fooasdf", 3);
              printf("%s0, ds.string);
              Ns_DStringFree(&ds); /* finished with dstring */

              If you need a null-terminated list of null-terminated
              strings, such as "foo bar  ", you would add one to
              the length of the appended strings to get the extra
              terminating null character. For example:

              Ns_DString ds;
              Ns_DStringInit(&ds);
              Ns_DStringNAppend(&ds, "foo", 4);
              Ns_DStringNAppend(&ds, "bar", 4);

       Ns_DStringPop(void)

              Pop an  Ns_DString  from  the  per-thread  cache,  allocating  the  space  for  the
              Ns_DString  if  necessary.   This  will  initialize  Thread Local Storage (TLS) and
              configure parameters on first use. TLS is a means of storing data associated with a
              particular  thread  within  the thread's context, so that it is always available to
              that thread. A pointer to the initialized Ns_DString is returned.

       Ns_DStringPrintf(dsPtr, fmt, ...)

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

              Ns_DString ds;

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

       Ns_DStringPush(dsPtr)

              Push  an Ns_DString onto the per-thread cache. The Ns_DString will be free'd if the
              maximum number of entries or the maximum size parameters have  been  exceeded.  The
              contents held by the Ns_DString are destroyed.

              This  is a performance function. Creating Ns_DStrings is a more expensive operation
              than cleaning out an already-existing Ns_DString and storing it for  later  use  by
              the same thread.

       Ns_DStringSetLength(dsPtr, length)

              The length of dsPtr is changed to length and a null byte is stored at that position
              in the string.  If length is larger than the space  allocated  for  dsPtr,  then  a
              panic occurs.

       Ns_DStringTrunc(dsPtr, length)

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

              Ns_DString ds;
              int i;
              Ns_DStringInit(&ds);

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

       Ns_DStringValue(dsPtr)

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

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

       Ns_DStringVarAppend(dsPtr, ...)

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

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

SEE ALSO

       nsd(1), info(n)

KEYWORDS