NAME

       Ns_ConnReturnOpenChannel,  Ns_ConnReturnOpenFd, Ns_ConnReturnFdEx, Ns_ConnReturnOpenFile -
       Routines to send open file content

SYNOPSIS

       #include "ns.h"
       int

       int
       Ns_ConnReturnOpenChannel(conn, status, type, chan, len)

       int
       Ns_ConnReturnOpenFd(conn, status, type, fd, len)

       int
       Ns_ConnReturnOpenFdex(conn, status, type, fd, off, len)

       int
       Ns_ConnReturnOpenFile(conn, status, type, fp, len)

ARGUMENTS

       Tcl_Channel   chan   (in)      Pointer to Tcl_Channel open for read.

       Ns_Conn       conn   (in)      Pointer to open connection.

       FILE          *fp    (in)      Pointer to stdio FILE open for read.

       off_t         off    (in)      Seek offset.

       int           fd     (int)     File descriptor open for read.

       int           status (in)      HTTP status code.

       char          *type  (in)      Pointer to mimetype string.
_________________________________________________________________

DESCRIPTION

       These routines are used to generate complete responses, including headers,  status  codes,
       content  types,  and the content copied from the given open file. They all return a status
       code which is NS_OK if the response was sent or NS_ERROR if an underlying call to sent the
       content  failed.   The  response  will  include the given HTTP status code, a content-type
       header with the given type, and a content-length header with the length specified by  len.
       No character output encoding or gzip compression is performed on the content.

       For  Ns_ConnReturnOpenFdEx,  copying  begins  at  the offset specified by the off argument
       Otherwise, these routines copy from the current read offset in the underlying  open  file.
       No  attempt  is made to serialize access to the underlying object so independent open file
       objects and/or mutex locking is necessary if the same file is being sent simultaneously to
       multiple clients.

NOTES

       Windows Support
              The  Ns_ConnReturnOpenFdEx  routine  is  not  currently supported on Windows.  When
              called on Windows, it will always return NS_ERROR.

       Truncated Result
              The server will construct a content-length header based on the given len  argument.
              However,   the  server  will  send  the  content  with  an  underlying  call  to  a
              cooresponding Ns_ConnSend function, e.g.,  Ns_ConnSendFd  for  Ns_ConnReturnOpenFd.
              These  functions  will  send  the requested content or all remaining content in the
              open file if less bytes  are  avilable  without  reporting  an  error  due  to  the
              truncated  response.   As the headers will have already been flushed before sending
              the content in this case, the content-length header will not be consistent with the
              actual  bytes  sent.   If  it is not possible to ensure the remaining bytes will be
              equal or greater to the requested bytes to send, it is possible to specify  -1  for
              len  to supress the content-length header entirely.  Most browsers will accept this
              resonse and simply calculate the length from  the  bytes  receieved  up  until  the
              socket is closed.

       Performance Consideration
              As  mentioned,  these  routines use underlying Ns_ConnSendFd style routines to copy
              and send the content from open files.  This is not the approach used by the builtin
              file-serving  code (aka the "fastpath").  The fastpath operates with filenames, not
              open file objects, and maintains a cached of pre-read or memory mapped  regions  to
              accelerate the common case of rapidly sending reasonably sized content to multiple,
              simultaneous  clients.   The  Ns_ConnReturnFile  routine  utilizes  the  underlying
              fastpath  and  thus  could  be  a  faster  means to send static files than directly
              opening files and calling these API's.

SEE ALSO

       Ns_ConnReturnFile(3), Ns_ConnFlush(3), Ns_ConnSendFd(3), Ns_ConnReturnData(3)

KEYWORDS

       connnection, response, file