Scroll to navigation

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

  
Returns the length of the memory buffer and/or the size of the open
      temporary file. Any trailing r0sent beyond the content from common
      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 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



  

    4.0
    AOLserver