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
SYNOPSIS¶
#include "ns.h"
int
Ns_ConnPrintfHeader(conn, fmt, ...)
int
Ns_ConnPuts(conn, string)
int
Ns_ConnSend(conn, bufs, nbufs)
int
Ns_ConnSendChannel(conn, chan, nsend)
int
Ns_ConnSendDString(conn, dsPtr)
int
Ns_ConnSendFd(conn, fd, nsend)
int
Ns_ConnSendFdEx(conn, fd, off, nsend)
int
Ns_ConnSendFp(conn, fp, nsend)
int
Ns_ConnWrite(conn, buf, len)
int
Ns_WriteConn(conn, buf, len)
ARGUMENTS¶
- char *buf (in)
- Pointer to bytes of specified length.
- Ns_Conn conn (in)
- Open connection on which to send content.
- Ns_DString dsPtr (in)
- Pointer to initialized dstring with content to send.
- int fd (in)
- File descriptor opened for read.
- char *fmt (in)
- Pointer to sprintf style format string which
specifies the types of the remaining variable number of arguments.
- FILE *fp (in)
- Stdio FILE pointer opened for read.
- int len (in)
- Length of bytes pointed to by buf.
- int nbufs (in)
- Number of iovec structures pointed to by bufs.
- int nsend (in)
- Number of bytes to send from object.
- off_t off (in)
- Offset into open file descriptor to begin sending
content.
- char *string (in)
- Pointer to null-terminated string.
- struct iovec bufs (in)
- Pointer to array of iovec structures.
- Tcl_Channel chan (in)
- Pointer to Tcl channel open for read.
DESCRIPTION¶
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
Ns_ConnQueueHeaders, if any, will be
sent before the requested user data.
In practice, higher level routines such as the
Ns_ConnReturn functions
and
Ns_ConnFlush 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.
- int Ns_ConnPrintfHeader(conn, fmt, ...)
- Contrary to it's name, this routine has nothing to do with
HTTP headers. Instead, it simply calls Ns_DStringPrintf with a
temporary dstring, the given fmt argument, and any variables
arguments and then calls Ns_ConnSendDString with the temporary
dstring. The result is NS_OK if all formatted bytes were sent, otherwise
NS_ERROR.
- int Ns_ConnPuts(conn, string)
- 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 Ns_WriteConn(conn, string, strlen(string)).
- int Ns_ConnSend(conn, bufs, nbufs)
- 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 bufs
argument is a pointer to an array of nbufs iovec structures. The
usage is similar to the the Unix writev system call. The iovec
structure is defined as:
struct iovec {
void *iov_base;
size_t iov_len
}
Each element of the structure should contain a pointer to valid user data
specified by
iov_base of length
iov_len. A NULL value for
iov_base and a cooresponding value of zero for
iov_len is valid
and will simply be skipped over when sending the total requested bytes.
- int Ns_ConnSendChannel(conn, chan,
nsend)
- This routine copies nsend 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.
- int Ns_ConnSendDString(conn, dsPtr)
- This routines sends all content which exists in the dstring
pointed to by dsPtr. The result is NS_OK if all bytes where sent,
otherwise NS_ERROR.
- int Ns_ConnSendFd(conn, fd, nsend)
- This routine copies nsend 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.
- int Ns_ConnSendFp(conn, fp, nsend)
- This routine copies nsend 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.
- int Ns_ConnSendFdEx(conn, fd, off,
nsend)
- This routine copies nsend 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 off parameter. (NOTE:
This routine is currently not supported on Win32 and always returns
NS_ERROR).
- int Ns_ConnWrite(conn, buf, len)
- This routine will send a single buffer pointed to by
buf of length len. The result is the number of bytes sent or
-1 on error. It is equivalent to calling Ns_ConnSend with an single
struct iovec.
- int Ns_WriteConn(conn, buf, len)
- This routine will send a single buffer pointed to by
buf of length len. The result is NS_OK if all content was
sent, otherwise NS_ERROR. It is equivalent to calling Ns_ConnWrite
and mapping the bytes sent or -1 error result to NS_OK or NS_ERROR.
EXMPLES¶
The following example demonstrates crafting some headers and then sending two
buffers of data. In this case,
Ns_ConnSend will actually call the
communications driver with three buffers, the first pointing to header data
queued for send by
Ns_ConnQueueHeaders 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:
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);
SEE ALSO¶
Ns_ConnClose(3),
Ns_ConnReturnHtml(3),
Ns_ConnFlush(3)
KEYWORDS¶
connection, i/o