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