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

NAME

       Ns_ConnPrintfHeader,  Ns_ConnPuts,  Ns_ConnSend,  Ns_ConnSendChannel,  Ns_ConnSendDString,
       Ns_ConnSendFd, Ns_ConnSendFdEx, Ns_ConnSendFp, Ns_ConnWrite, Ns_WriteConn  -  Routines  to
       write data to the connection

SYNOPSIS

       #include "ns.h"

       int
       Ns_ConnPrintfHeader(conn, fmt, ...)

       int
       Ns_ConnPuts(conn, string)

       int
       Ns_ConnSend(conn, bufs, nbufs)

       int
       Ns_ConnSendChannel(conn, chan, nsend)

       int
       Ns_ConnSendDString(conn, dsPtr)

       int
       Ns_ConnSendFd(conn, fd, nsend)

       int
       Ns_ConnSendFdEx(conn, fd, off, nsend)

       int
       Ns_ConnSendFp(conn, fp, nsend)

       int
       Ns_ConnWrite(conn, buf, len)

       int
       Ns_WriteConn(conn, buf, len)

ARGUMENTS

       char           *buf           (in)      Pointer to bytes of specified length.

       Ns_Conn        conn           (in)      Open connection on which to send content.

       Ns_DString     dsPtr          (in)      Pointer  to  initialized  dstring  with content to
                                               send.

       int            fd             (in)      File descriptor opened for read.

       char           *fmt           (in)      Pointer  to  sprintf  style  format  string  which
                                               specifies  the  types  of  the  remaining variable
                                               number of arguments.

       FILE           *fp            (in)      Stdio FILE pointer opened for read.

       int            len            (in)      Length of bytes pointed to by buf.

       int            nbufs          (in)      Number of iovec structures pointed to by bufs.

       int            nsend          (in)      Number of bytes to send from object.

       off_t          off            (in)      Offset into open file descriptor to begin  sending
                                               content.

       char           *string        (in)      Pointer to null-terminated string.

       struct iovec   bufs           (in)      Pointer to array of iovec structures.

       Tcl_Channel    chan           (in)      Pointer to Tcl channel open for read.
_________________________________________________________________

DESCRIPTION

       These  functions are the lowest level routines which support sending content directly to a
       connection through the connection's communications driver  (e.g.,  nssock  or  nsopenssl).
       They  all  attempt  to send the entire requested output, blocking the calling thread up to
       the  driver-specific  timeout  if  necessary.   Header   data   queued   for   send   with
       Ns_ConnQueueHeaders, if any, will be sent before the requested user data.

       In  practice,  higher  level routines such as the Ns_ConnReturn functions and Ns_ConnFlush
       are used to generate complete responses instead of these lower level routines.  The higher
       level  routines  construct  appropriate  headers,  manage  output  character encoding, and
       support gzip compression, calling these lower level routines as needed.

       int Ns_ConnPrintfHeader(conn, fmt, ...)
              Contrary to it's name, this routine has nothing to do with HTTP headers.   Instead,
              it  simply calls Ns_DStringPrintf with a temporary dstring, the given fmt argument,
              and any variables arguments and then calls Ns_ConnSendDString  with  the  temporary
              dstring.  The result is NS_OK if all formatted bytes were sent, otherwise NS_ERROR.

       int Ns_ConnPuts(conn, string)
              This  routines  sends  a  null-terminated string to the client and returns NS_OK if
              successful or NS_ERROR on failure.  It is equivalent to Ns_WriteConn(conn,  string,
              strlen(string)).

       int Ns_ConnSend(conn, bufs, nbufs)
              This  is the lowest level routine which calls the connection's communication driver
              to send an array of zero or more buffers.  The result is the total number of  bytes
              sent  which  should  equal  the total requested data or -1 on error.  The number of
              bytes sent from queued header data, if any, is not included  in  the  result.   The
              bufs  argument  is  a  pointer to an array of nbufs iovec structures.  The usage is
              similar to the the Unix writev system call.  The iovec structure is defined as:

                struct iovec {
                   void            *iov_base;
                   size_t           iov_len
                }

       Each element of the structure should contain a pointer to valid  user  data  specified  by
       iov_base  of  length iov_len.  A NULL value for iov_base and a cooresponding value of zero
       for iov_len is valid and will simply be skipped over  when  sending  the  total  requested
       bytes.

       int Ns_ConnSendChannel(conn, chan, nsend)
              This  routine  copies nsend bytes from the open Tcl channel to the connection.  The
              result is NS_OK if all bytes available in the open channel or all  bytes  requested
              where sent, otherwise NS_ERROR.

       int Ns_ConnSendDString(conn, dsPtr)
              This  routines  sends  all content which exists in the dstring pointed to by dsPtr.
              The result is NS_OK if all bytes where sent, otherwise NS_ERROR.

       int Ns_ConnSendFd(conn, fd, nsend)
              This routine copies nsend bytes from the open file descriptor  to  the  connection.
              The  result is NS_OK if all bytes available in the open file or all bytes requested
              where sent, otherwise NS_ERROR.  Copying begins from the current offset.

       int Ns_ConnSendFp(conn, fp, nsend)
              This routine copies nsend bytes from the open stdio FILE to  the  connection.   The
              result  is  NS_OK  if  all  bytes available in the open file or all bytes requested
              where sent, otherwise NS_ERROR.  Copying begins from the current offset.

       int Ns_ConnSendFdEx(conn, fd, off, nsend)
              This routine copies nsend bytes from the open file descriptor  to  the  connection.
              The  result is NS_OK if all bytes available in the open file or all bytes requested
              where sent, otherwise NS_ERROR.  Copying begins from the offset given  in  the  off
              parameter.   (NOTE:  This  routine  is  currently not supported on Win32 and always
              returns NS_ERROR).

       int Ns_ConnWrite(conn, buf, len)
              This routine will send a single buffer pointed to by buf of length len.  The result
              is  the  number  of  bytes  sent  or  -1  on  error.   It  is equivalent to calling
              Ns_ConnSend with an single struct iovec.

       int Ns_WriteConn(conn, buf, len)
              This routine will send a single buffer pointed to by buf of length len.  The result
              is  NS_OK if all content was sent, otherwise NS_ERROR.  It is equivalent to calling
              Ns_ConnWrite and mapping the bytes sent or -1 error result to NS_OK or NS_ERROR.

EXMPLES

       The following example demonstrates crafting some headers and then sending two  buffers  of
       data.   In  this case, Ns_ConnSend will actually call the communications driver with three
       buffers, the first pointing to header data queued for send by Ns_ConnQueueHeaders followed
       by the two user data buffers.  The result, assuming all three buffers are resonably small,
       is likely an efficient single send on the socket:

                struct iovec iov[2];
                int contentlength;

                iov[0].iov_base = firstbuf;
                iov[0].iov_len  = firstlen;
                iov[1].iov_base = secondbuf;
                iov[1].iov_len= secondlen;
                contentlength = iov[0].iov_len + iov[1].iov_len;
                Ns_ConnSetRequiredHeaders(conn, "text/html", contentlength);
                Ns_ConnQueueHeaders(conn, 200);
                if (Ns_ConnSend(conn, iov, contentlength) != contentlength) {
                   ... error, e.g., connection drop ...
                }
                Ns_ConnClose(conn);

SEE ALSO

       Ns_ConnClose(3), Ns_ConnReturnHtml(3), Ns_ConnFlush(3)

KEYWORDS

       connection, i/o