SYNOPSIS

#include "ns.h"

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 sent 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.

KEYWORDS