'\"
'\" The contents of this file are subject to the AOLserver Public License
'\" Version 1.1 (the "License"); you may not use this file except in
'\" compliance with the License. You may obtain a copy of the License at
'\" http://aolserver.com/.
'\"
'\" Software distributed under the License is distributed on an "AS IS"
'\" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
'\" the License for the specific language governing rights and limitations
'\" under the License.
'\"
'\" The Original Code is AOLserver Code and related documentation
'\" distributed by AOL.
'\" 
'\" The Initial Developer of the Original Code is America Online,
'\" Inc. Portions created by AOL are Copyright (C) 1999 America Online,
'\" Inc. All Rights Reserved.
'\"
'\" Alternatively, the contents of this file may be used under the terms
'\" of the GNU General Public License (the "GPL"), in which case the
'\" provisions of GPL are applicable instead of those above.  If you wish
'\" to allow use of your version of this file only under the terms of the
'\" GPL and not to allow others to use your version of this file under the
'\" License, indicate your decision by deleting the provisions above and
'\" replace them with the notice and other provisions required by the GPL.
'\" If you do not delete the provisions above, a recipient may use your
'\" version of this file under either the License or the GPL.
'\" 
'\"
'\" $Header: /cvsroot/aolserver/aolserver/doc/Ns_ConnContent.3,v 1.3 2006/04/19 17:37:30 jgdavidson Exp $
'\"
'\" 
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2006/06/26 00:29:11 jgdavidson Exp $
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..

.TH Ns_ConnContent 3aolserver 4.0 AOLserver "AOLserver Library Procedures"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
Ns_ConnContent, Ns_ConnContentLength, Ns_ConnContentFd, Ns_ConnContentOnDisk \- Routines to access request content
.SH SYNOPSIS
.nf
\fB#include "ns.h"\fR
.sp
char *
\fBNs_ConnContent\fR(\fINs_Conn *conn\fR)
.sp
int
\fBNs_ConnContentLength\fR(\fINs_Conn *conn\fR)
.sp
int
\fBNs_ConnContentFd\fR(\fINs_Conn *conn\fR)
.sp
int
\fBNs_ConnContentOnDisk\fR(\fINs_Conn *conn\fR)
.SH ARGUMENTS
.AS Ns_Conn *conn in
.AP Ns_Conn *conn in
Pointer to given connection. 
.sp
.BE
.SH DESCRIPTION
.PP
These procedures provide access to the request content sent with a
request.

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

.TP
int \fBNs_ConnContentFd\fR
Returns a file descriptor to an open temporary file which contains
the content.

.TP
int \fBNs_ConnContentLength\fR
Returns the length of the memory buffer and/or the size of the open
temporary file.  Any trailing \r\n sent beyond the content from
common browsers on a POST request is not included.

.TP
int \fBNs_ConnContentOnDisk\fR
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.

.SH "CONTENT PRE-READ"
.PP
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 \fImaxcontent\fR
virtual server setting are rejected, requests with content between
\fImaxinput\fR and \fImaxcontent\fR are spooled to a temp file, and
small requests (the majority of simple POST's) are copied to memory.

.PP
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, \fBNs_ConnRead\fR,
are now emulated on top of the \fBNs_ConnContent\fR.

.SH "RESOURCE MANAGEMENT"
.PP
\fBNs_ConnContentFd\fR returns an open file descriptor allocated
by a call \fBNs_GetTemp\fR 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 \fBns_conn contentchannel\fR option.
.PP
On a call to \fBNs_ConnContent\fR, 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 \fBNs_ConnContentFd\fR, 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.

.SH "DESIGN NOTES AND LARGE CONTENT CONSIDERATIONS"
.PP
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 \fBNs_ConnGetQuery\fR
for a \fImultipart/file-upload\fR POST will result in an implicit
call to \fBNs_ConnContent\fR to parse the fields.  This could require
significant temporary virtual memory plus dynamic memory to copy
non-file fields into the resulting \fINs_Set\fR. See the \fIns_limits\fR
command to control maximum resource requirements.
.PP
For custom apps, an extension could work with the underlying open
file via \fBNs_ConnContentFd\fR or \fBns_connn contentchannel\fR
to avoid large virtual memory requirements subject to disk space
availability.  To avoid inadvertant memory mapping of a large upload
by other extensions calling \fBNs_ConnGetQuery\fR, consider using
a HTTP method other than \fIGET\fR or \fIPOST\fR required by
\fBNs_ConnGetQuery\fR, e.g., \fIPUT\fR.

.SH "SEE ALSO"
Ns_Conn(3), Ns_ConnRead(3), ns_limits(n), ns_conn(n)

.SH KEYWORDS
connection, content