ns_conncopytochannel(3aolserv) [debian man page]

Ns_ConnCopy(3aolserver) 				   AOLserver Library Procedures 				   Ns_ConnCopy(3aolserver)

__________________________________________________________________________________________________________________________________________________

NAME

       Ns_ConnCopyToChannel, Ns_ConnCopyToDString, Ns_ConnCopyToFd, Ns_ConnCopyToFile - Copy request content to open file or dstring

SYNOPSIS

       #include "ns.h"

       int
       Ns_ConnCopyToChannel(conn, ncopy, chan)

       int
       Ns_ConnCopyToDString(conn, ncopy, dsPtr)

       int
       Ns_ConnCopyToFd(conn, ncopy, fd)

       int
       Ns_ConnCopyToFile(conn, ncopy, fp)

ARGUMENTS

       Ns_Channel   chan   (in)      Pointer to Tcl channel open for write.

       Ns_Conn	    conn   (in)      Pointer to open connection.

       Ns_DString   dsPtr  (in)      Initialized dstring.

       int	    fd	   (in)      File descriptor open for write.

       FILE	    fp	   (in)      Stdio FILE pointer open for write.

       int	    ncopy  (in)      Number of bytes to copy.
_________________________________________________________________

DESCRIPTION

       These  functions  copy  content from an open connection request to the given open file descriptor, FILE, dstring, or Tcl_Channel.  The rou-
       tines work by copying from the content buffer; see the man page on Ns_ConnContent for how this buffer is managed for both small	and  large
       requests.

       The functions all return the number of bytes copied which will match the requested ncopy argument unless there is an error writing the con-
       tent or the requested bytes is greater than the number of bytes still available to be read.  An internal  offset  into  the  connection	is
       maintained  and	is  shared  with  routines  such as Ns_ConnRead which also consume content from the same buffer.  Note that routines which
       access the entire content, e.g., Ns_ConnContent, Ns_ConnContentFd, or Ns_ConnGetQuery will continue to provide access to the entire request
       regardless if one of the Ns_ConnCopy or Ns_ConnRead functions have been used.

EXAMPLES

       The following example demonstrates copying user data to a temp file:

		fd = open("myfile.out", O_WRONLY|O_BINARY);
		len = Ns_ConnContentLength(conn);
		if (Ns_ConnCopyToFd(conn, len, fd) != len) {
		   ... error writing content or content already consumed ...
		}

SEE ALSO

       Ns_ConnRead(3), Ns_ConnReadLine(3), Ns_ConnContent(3), Ns_ConnContentFd(3)

KEYWORDS

       connection, content, read

AOLserver								4.0						   Ns_ConnCopy(3aolserver)

Ns_ConnRead(3aolserver) 				   AOLserver Library Procedures 				   Ns_ConnRead(3aolserver)

__________________________________________________________________________________________________________________________________________________

NAME

       Ns_ConnGets, Ns_ConnRead, Ns_ConnFlushHeaders, Ns_ConnReadHeaders, Ns_ConnReadLine - Routines to copy connection content

SYNOPSIS

       #include "ns.h"

       char *
       Ns_ConnGets(buf, bufsize, conn)

       int
       Ns_ConnFlushContent(conn)

       int
       Ns_ConnRead(conn, vbuf, toread)

       int
       Ns_ConnReadHeaders(conn, set, nreadPtr)

       int
       Ns_ConnReadLine(conn, dsPtr, nreadPtr)

ARGUMENTS

       char	    *buf    (in)      Pointer to string buffer of length bufsize.

       int	    bufsize (in)      Length of buffer pointer to by buf.

       Ns_Conn	    conn    (in)      Pointer to open connection.

       Ns_DString   dsPtr   (out)     Pointer to initialized dstring to receive copied line.

       int	    *nreadPtr(out)    Pointer to integer to receive number of bytes copied.

       Ns_Set	    set     (in/out)  Pointer to initialized Ns_Set to copy headers.

       int	    toread  (in)      Number of bytes to copy to location starting at vbuf

       void	    *vbuf   (in)      Pointer to memory location to copy content.
_________________________________________________________________

DESCRIPTION

       These  routines	support  copying  content  from the connection.  They all operate by copying from the content buffer returned by a call to
       Ns_ConnContent, maintaining a private, shared offset into the content.  This means that these routines are not  actually  reading  directly
       from  the network and thus will not block waiting for input.  See the man page on Ns_ConnContent for details on how the content is pre-read
       by the server and how resources are managed for small and large content requests.

       char *Ns_ConnGets(buf, bufsize, conn)
	      Copies the next available line of text from the content to the given buf string, up to the given bufsize less space for  a  trailing
	      null ().  The result is a pointer to buf or NULL if an underlying call to Ns_ConnRead fails.

       int Ns_ConnFlushContent(conn)
	      Performs	a  logical  flush of the underlying content available to these routines.  It simply moves the private offset to the end of
	      the content.  The result is NS_OK unless an underlying call to Ns_ConnContent failed in which case NS_ERROR is returned.

       int Ns_ConnRead(conn, vbuf, toread)
	      Copies up to toread bytes from the content to the memory location pointed to by vbuf.  The result is  the  number  of  bytes  copied
	      which will match toread unless less bytes are available in the input or -1 if an underlying call to Ns_ConnContent failed.

       int Ns_ConnReadHeaders(conn, set, nreadPtr)
	      Copies lines up to the first blank line or end of content up to the maximum header read size specified with the communication driver
	      "maxheader" parameter (default: 32k).  Each line is parsed into "key: value" pairs into the given Ns_Set pointed to be the set argu-
	      ment  using  the Ns_ParseHeader routine with the Ns_HeaderCaseDisposition specified by the "headercase" server option (default: Pre-
	      serve).  The result is NS_OK if all lines were consumed or NS_ERROR on overflow beyond the max header limit or if there was an error
	      with  the  underlying  call  to Ns_ConnRead (including an error of a single line beyond the max line limit as described below).  The
	      integer pointed to by the nreadPtr argument, if given, is updated with the total number of bytes consumed.  This routine can be use-
	      ful when parsing multipart/form-data content to collect headers for each part.

       int Ns_ConnReadLine(conn, dsPtr, nreadPtr)
	      Copies the next available line to the given dsPtr dstring.  The integer pointed to by nreadPtr, if present, is updated with the num-
	      ber of bytes copied.  The line will not include the trailing 
 or 
 if present.  The function will return NS_OK unless an under-
	      lying  call  to Ns_ConnContent failed or the line exceeds the maximum line read size specified by the communication driver "maxline"
	      parameter (default: 4k).	This routine differs from Ns_ConnGets in that it copies the result to a dstring  instead  of  a  character
	      buffer, requires a full or end-of-content terminated line, and enforces the maxline limit.

SEE ALSO

       Ns_ConnContent(3), Ns_ParseHeader(3)

KEYWORDS

       connection, read, content

AOLserver								4.0						   Ns_ConnRead(3aolserver)