Ns_ConnRead(3)

NAME
Ns_ConnGets, Ns_ConnRead, Ns_ConnFlushHeaders, Ns_ConnReadHeaders, Ns_ConnReadLine - Routines to copy connection content

SYNOPSIS
#include "ns.h"

char *
Ns_ConnGets(buf, bufsize, conn)

int
Ns_ConnFlushContent(conn)

int
Ns_ConnRead(conn, vbuf, toread)

int
Ns_ConnReadHeaders(conn, set, nreadPtr)

int
Ns_ConnReadLine(conn, dsPtr, nreadPtr)

ARGUMENTS
Pointer to string buffer of length bufsize. Length of buffer pointer to by buf. Pointer to open connection. Pointer to initialized dstring to receive copied line. Pointer to integer to receive number of bytes copied. Pointer to initialized Ns_Set to copy headers. Number of bytes to copy to location starting at vbuf Pointer to memory location to copy content.

DESCRIPTION

These routines support copying content from the connection. They all operate by copying from the content buffer returned by a call to Ns_ConnContent, maintaining a private, shared offset into the content. This means that these routines are not actually reading directly from the network and thus will not block waiting for input. See the man page on Ns_ConnContent for details on how the content is pre-read by the server and how resources are managed for small and large content requests.

char *Ns_ConnGets(buf, bufsize, conn)
    Copies the next available line of text from the content to the given buf string, up to the given bufsize less space for a trailing null (\0). The result is a pointer to buf or NULL if an underlying call to Ns_ConnRead fails.

int Ns_ConnFlushContent(conn)
    Performs a logical flush of the underlying content available to these routines. It simply moves the private offset to the end of the content. The result is NS_OK unless an underlying call to Ns_ConnContent failed in which case NS_ERROR is returned.

int Ns_ConnRead(conn, vbuf, toread)
    Copies up to toread bytes from the content to the memory location pointed to by vbuf. The result is the number of bytes copied which will match toread unless less bytes are available in the input or -1 if an underlying call to Ns_ConnContent failed.

int Ns_ConnReadHeaders(conn, set, nreadPtr)
    Copies lines up to the first blank line or end of content up to the maximum header read size specified with the communication driver "maxheader" parameter (default: 32k). Each line is parsed into "key: value" pairs into the given Ns_Set pointed to be the set argument using the Ns_ParseHeader routine with the Ns_HeaderCaseDisposition specified by the "headercase" server option (default: Preserve). The result is NS_OK if all lines were consumed or NS_ERROR on overflow beyond the max header limit or if there was an error with the underlying call to Ns_ConnRead (including an error of a single line beyond the max line limit as described below). The integer pointed to by the nreadPtr argument, if given, is updated with the total number of bytes consumed. This routine can be useful when parsing multipart/form-data content to collect headers for each part.

int Ns_ConnReadLine(conn, dsPtr, nreadPtr)
    Copies the next available line to the given dsPtr dstring. The integer pointed to by nreadPtr, if present, is updated with the number of bytes copied. The line will not include the trailing \r\n or \n if present. The function will return NS_OK unless an underlying call to Ns_ConnContent failed or the line exceeds the maximum line read size specified by the communication driver "maxline" parameter (default: 4k). This routine differs from Ns_ConnGets in that it copies the result to a dstring instead of a character buffer, requires a full or end-of-content terminated line, and enforces the maxline limit.

SEE ALSO
Ns_ConnContent(3), Ns_ParseHeader(3)

KEYWORDS
connection, read, content