'\" '\" 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_ConnSend.3,v 1.6 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_ConnSend 3aolserver 4.5 AOLserver "AOLserver Library Procedures" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME Ns_ConnPrintfHeader, Ns_ConnPuts, Ns_ConnSend, Ns_ConnSendChannel, Ns_ConnSendDString, Ns_ConnSendFd, Ns_ConnSendFdEx, Ns_ConnSendFp, Ns_ConnWrite, Ns_WriteConn \- Routines to write data to the connection .SH SYNOPSIS .nf \fB#include "ns.h"\fR .sp int \fBNs_ConnPrintfHeader(\fIconn, fmt, ...\fR) .sp int \fBNs_ConnPuts\fR(\fIconn, string\fR) .sp int \fBNs_ConnSend\fR(\fIconn, bufs, nbufs\fR) .sp int \fBNs_ConnSendChannel\fR(\fIconn, chan, nsend\fR) .sp int \fBNs_ConnSendDString\fR(\fIconn, dsPtr\fR) .sp int \fBNs_ConnSendFd\fR(\fIconn, fd, nsend\fR) .sp int \fBNs_ConnSendFdEx\fR(\fIconn, fd, off, nsend\fR) .sp int \fBNs_ConnSendFp\fR(\fIconn, fp, nsend\fR) .sp int \fBNs_ConnWrite\fR(\fIconn, buf, len\fR) .sp int \fBNs_WriteConn\fR(\fIconn, buf, len\fR) .SH ARGUMENTS .AS "struct iovec" "struct iovec" in .AP char *buf in Pointer to bytes of specified length. .AP Ns_Conn conn in Open connection on which to send content. .AP Ns_DString dsPtr in Pointer to initialized dstring with content to send. .AP int fd in File descriptor opened for read. .AP char *fmt in Pointer to \fBsprintf\fR style format string which specifies the types of the remaining variable number of arguments. .AP FILE *fp in Stdio FILE pointer opened for read. .AP int len in Length of bytes pointed to by \fIbuf\fR. .AP int nbufs in Number of iovec structures pointed to by \fIbufs\fR. .AP int nsend in Number of bytes to send from object. .AP off_t off in Offset into open file descriptor to begin sending content. .AP char *string in Pointer to null-terminated string. .AP "struct iovec" bufs in Pointer to array of iovec structures. .AP Tcl_Channel chan in Pointer to Tcl channel open for read. .BE .SH DESCRIPTION .PP These functions are the lowest level routines which support sending content directly to a connection through the connection's communications driver (e.g., nssock or nsopenssl). They all attempt to send the entire requested output, blocking the calling thread up to the driver-specific timeout if necessary. Header data queued for send with \fBNs_ConnQueueHeaders\fR, if any, will be sent before the requested user data. .PP In practice, higher level routines such as the \fBNs_ConnReturn\fR functions and \fBNs_ConnFlush\fR are used to generate complete responses instead of these lower level routines. The higher level routines construct appropriate headers, manage output character encoding, and support gzip compression, calling these lower level routines as needed. .TP int \fBNs_ConnPrintfHeader\fR(\fIconn, fmt, ...\fR) Contrary to it's name, this routine has nothing to do with HTTP headers. Instead, it simply calls \fBNs_DStringPrintf\fR with a temporary dstring, the given \fIfmt\fR argument, and any variables arguments and then calls \fBNs_ConnSendDString\fR with the temporary dstring. The result is NS_OK if all formatted bytes were sent, otherwise NS_ERROR. .TP int \fBNs_ConnPuts\fR(\fIconn, string\fR) This routines sends a null-terminated string to the client and returns NS_OK if successful or NS_ERROR on failure. It is equivalent to \fBNs_WriteConn\fR(\fIconn, string, strlen(string)\fR). .TP int \fBNs_ConnSend\fR(\fIconn, bufs, nbufs\fR) This is the lowest level routine which calls the connection's communication driver to send an array of zero or more buffers. The result is the total number of bytes sent which should equal the total requested data or -1 on error. The number of bytes sent from queued header data, if any, is not included in the result. The \fIbufs\fR argument is a pointer to an array of \fInbufs\fR iovec structures. The usage is similar to the the Unix \fBwritev\fR system call. The iovec structure is defined as: .CS struct iovec { void *iov_base; size_t iov_len } .CE Each element of the structure should contain a pointer to valid user data specified by \fIiov_base\fR of length \fIiov_len\fR. A NULL value for \fIiov_base\fR and a cooresponding value of zero for \fIiov_len\fR is valid and will simply be skipped over when sending the total requested bytes. .TP int \fBNs_ConnSendChannel\fR(\fIconn, chan, nsend\fR) This routine copies \fInsend\fR bytes from the open Tcl channel to the connection. The result is NS_OK if all bytes available in the open channel or all bytes requested where sent, otherwise NS_ERROR. .TP int \fBNs_ConnSendDString\fR(\fIconn, dsPtr\fR) This routines sends all content which exists in the dstring pointed to by \fIdsPtr\fR. The result is NS_OK if all bytes where sent, otherwise NS_ERROR. .TP int \fBNs_ConnSendFd\fR(\fIconn, fd, nsend\fR) This routine copies \fInsend\fR bytes from the open file descriptor to the connection. The result is NS_OK if all bytes available in the open file or all bytes requested where sent, otherwise NS_ERROR. Copying begins from the current offset. .TP int \fBNs_ConnSendFp\fR(\fIconn, fp, nsend\fR) This routine copies \fInsend\fR bytes from the open stdio FILE to the connection. The result is NS_OK if all bytes available in the open file or all bytes requested where sent, otherwise NS_ERROR. Copying begins from the current offset. .TP int \fBNs_ConnSendFdEx\fR(\fIconn, fd, off, nsend\fR) This routine copies \fInsend\fR bytes from the open file descriptor to the connection. The result is NS_OK if all bytes available in the open file or all bytes requested where sent, otherwise NS_ERROR. Copying begins from the offset given in the \fIoff\fR parameter. (NOTE: This routine is currently not supported on Win32 and always returns NS_ERROR). .TP int \fBNs_ConnWrite\fR(\fIconn, buf, len\fR) This routine will send a single buffer pointed to by \fIbuf\fR of length \fIlen\fR. The result is the number of bytes sent or -1 on error. It is equivalent to calling \fBNs_ConnSend\fR with an single struct iovec. .TP int \fBNs_WriteConn\fR(\fIconn, buf, len\fR) This routine will send a single buffer pointed to by \fIbuf\fR of length \fIlen\fR. The result is NS_OK if all content was sent, otherwise NS_ERROR. It is equivalent to calling \fBNs_ConnWrite\fR and mapping the bytes sent or -1 error result to NS_OK or NS_ERROR. .SH EXMPLES .PP The following example demonstrates crafting some headers and then sending two buffers of data. In this case, \fBNs_ConnSend\fR will actually call the communications driver with three buffers, the first pointing to header data queued for send by \fBNs_ConnQueueHeaders\fR followed by the two user data buffers. The result, assuming all three buffers are resonably small, is likely an efficient single send on the socket: .CS struct iovec iov[2]; int contentlength; iov[0].iov_base = firstbuf; iov[0].iov_len = firstlen; iov[1].iov_base = secondbuf; iov[1].iov_len = secondlen; contentlength = iov[0].iov_len + iov[1].iov_len; Ns_ConnSetRequiredHeaders(conn, "text/html", contentlength); Ns_ConnQueueHeaders(conn, 200); if (Ns_ConnSend(conn, iov, contentlength) != contentlength) { ... error, e.g., connection drop ... } Ns_ConnClose(conn); .CE .SH "SEE ALSO" Ns_ConnClose(3), Ns_ConnReturnHtml(3), Ns_ConnFlush(3) .SH KEYWORDS connection, i/o