ns_conncopytodstring(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_ConnContent(3aolserver)				   AOLserver Library Procedures 				Ns_ConnContent(3aolserver)

__________________________________________________________________________________________________________________________________________________

NAME

       Ns_ConnContent, Ns_ConnContentLength, Ns_ConnContentFd, Ns_ConnContentOnDisk - Routines to access request content

SYNOPSIS

       #include "ns.h"

       char *
       Ns_ConnContent(Ns_Conn *conn)

       int
       Ns_ConnContentLength(Ns_Conn *conn)

       int
       Ns_ConnContentFd(Ns_Conn *conn)

       int
       Ns_ConnContentOnDisk(Ns_Conn *conn)

ARGUMENTS

       Ns_Conn	 *conn	 (in)	   Pointer to given connection.

_________________________________________________________________

DESCRIPTION

       These procedures provide access to the request content sent with a request.

       char *Ns_ConnContent
	      Returns a pointer to the content in memory.  The result of Ns_ConnContent is not guarenteed to be null-terminated.  Safe code should
	      be careful to use the result of Ns_ConnContentLength to avoid overrun.

       int Ns_ConnContentFd
	      Returns a file descriptor to an open temporary file which contains the content.

       int Ns_ConnContentLength 										sent beyond the content from  com-
	      Returns the length of the memory buffer and/or the size of the open temporary file.  Any trailing
	      mon browsers on a POST request is not included.

       int Ns_ConnContentOnDisk
	      Returns  1  if the content is currently on disk, such that a call to Ns_ConnContentFd will not cause a new file to be created.  When
	      it returns 0, a call to Ns_ConnContent will not require a mmap() call.

CONTENT PRE-READ
       While receiving the request before connection processing, the server will pre-read the entire content body and either copy the  content	to
       memory or spool it to an open file depending on virtual server config settings.	Requests with content beyond the maxcontent virtual server
       setting are rejected, requests with content between maxinput and maxcontent are spooled to a temp file, and small requests (the majority of
       simple POST's) are copied to memory.

       There is no need for a request processing extension to consider possible delays in reading content from the client as all content is avail-
       able before connection processing begins.  The rationale for this approach is that the driver thread can efficiently multiplex reading con-
       tent  for  serveral request, tolerating any network delays.  Legacy direct content reading routines, for example, Ns_ConnRead, are now emu-
       lated on top of the Ns_ConnContent.

RESOURCE MANAGEMENT

       Ns_ConnContentFd returns an open file descriptor allocated by a call Ns_GetTemp and must not be closed as it is owned by  the  server  core
       and  will  be  closed at the end of the connection.  In addition, there is no filename for the open file as the file is removed when opened
       for security reasons and to ensure garbage collection.  In practice, the open file should be used to verify, parse, and copy content  else-
       where as required.  Access at the Tcl level is also available via the ns_conn contentchannel option.

       On  a  call to Ns_ConnContent, either the existing memory buffer will be returned or the temp file will be memory mapped on the first call.
       This will require temporary virtual memory to support the mapping until the end of the connection.  Likewise, on the first call to  Ns_Con-
       nContentFd,  if a temp file does not already exists one will be allocated and the memory content will be spooled to the file.  These seman-
       tics allow one to access the content in either mode, assuming resources are available, regardless of the original location of the content.

DESIGN NOTES AND LARGE CONTENT CONSIDERATIONS

       The design goal of the server is to support the ordinary case of reasonably small  content  requests  (i.e.,  POST  forms  and  small  file
       uploads)  in a convienent way without limiting a custom app to support very large requests.  In particular, a call to Ns_ConnGetQuery for a
       multipart/file-upload POST will result in an implicit call to Ns_ConnContent to parse the fields.  This could require significant temporary
       virtual memory plus dynamic memory to copy non-file fields into the resulting Ns_Set. See the ns_limits command to control maximum resource
       requirements.

       For custom apps, an extension could work with the underlying open file via Ns_ConnContentFd or ns_connn contentchannel to avoid large  vir-
       tual  memory  requirements  subject  to disk space availability.  To avoid inadvertant memory mapping of a large upload by other extensions
       calling Ns_ConnGetQuery, consider using a HTTP method other than GET or POST required by Ns_ConnGetQuery, e.g., PUT.

SEE ALSO

       Ns_Conn(3), Ns_ConnRead(3), ns_limits(n), ns_conn(n)

KEYWORDS

       connection, content

AOLserver								4.0						Ns_ConnContent(3aolserver)