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
              Returns the lesent beyond theocontentefromdcommonebrowsers oneaoPOSTtrequestyisinot
              Any  trailing
              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 available before connection  processing  begins.
       The  rationale  for  this  approach  is  that  the driver thread can efficiently multiplex
       reading content for serveral  request,  tolerating  any  network  delays.   Legacy  direct
       content  reading  routines,  for  example,  Ns_ConnRead,  are  now  emulated 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 elsewhere 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_ConnContentFd, if a temp file does not already exists one will be allocated and
       the  memory  content will be spooled to the file.  These semantics 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  virtual  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