NaviServer - programmable web server

[ Main Table Of Contents | Table Of Contents | Keyword Index ]

# ns_return(n) 4.99.8 naviserver "NaviServer Built-in Commands"

## Name

ns_return - Return a complete HTTP response

## Table Of Contents

## Synopsis

- ns_return ?-binary? status mime-type body
- ns_returnfile status mime-type filepath
- ns_returnfp status mime-type channel length
- ns_respond ?-status status? ?-type mime-type? ?-length int? ?-headers setid? ?-string body? ?-binary body? ?-file filepath? ?-fileid channel?

## Description

These commands are used to construct a complete HTTP response and return it to the requesting client. The response may be transcoded into a different encoding, compressed and/or sent in chunks as automatically negotiated by the client and server settings.

Unless otherwise noted, these commands return true if the command failed and false otherwise. All of them can raise an error if their arguments are incorrect.

The behavior of the file delivery commands ns_returnfile and ns_repond is influenced by the fastpath settings, that define, how static files are served. The fastpath settings are described in the CONFIGURATION section at the end of this page.

## COMMANDS

ns_return ?-binary? status mime-type body

  Return a complete response to the client consisting of the given body and a set of HTTP headers. status is an integer HTTP status code such as 200 (OK) or 404 (Not Found). When the optional flag -binary is used, the content of the tcl byte-array is transmitted.

  mime-type is the mime-type of the body. If a charset attribute is included in the mime-type it will be used to set the encoding of the connection. Otherwise, the connection encoding will be used to construct a charset attribute for the mime-type.

  If body is Tcl byte-array object then no transcoding will take place. Otherwise, the encoding in effect for the current connection will be used to encode the body.

  After the command completes the connection is returned to the driver thread to be closed or monitored for keep-alive and the calling connection thread continues to execute code.

ns_returnfile status mime-type filepath

  Return the given file as the complete response body. Headers are constructed using status, mime-type and any pending headers set using ns_conn outputheaders. The bytes of the file are not transformed in any way.

  After the command completes the connection is returned to the driver thread to be closed or monitored for keep-alive and the calling connection thread continues to execute code.

ns_returnfp status mime-type channel length

  Return length bytes from channel as the response body. The current offset of the channel is the beginning of the body -- the offset will be left at length bytes. The bytes of the file are not transformed in any way.

  After the command completes the connection is returned to the driver thread to be closed or monitored for keep-alive and the calling connection thread continues to execute code.

ns_respond ?-status status? ?-type mime-type? ?-length int? ?-headers setid? ?-string body? ?-binary body? ?-file filepath? ?-fileid channel?

  Return a complete response to the client using exactly one of -string, -binary, -file or -fileid as the body.

  After the command completes the connection is returned to the driver thread to be closed or monitored for keep-alive and the calling connection thread continues to execute code.

  -status status

    The HTTP status code. Default 200.

  -type mime-type

    The mime-type of the response body. Default */*.

  -headers setid

    A set of headers which will replace any pending headers for the response.

  -string body

    The Tcl string to send as the response body. The body may be encoded into an appropriate character set if required by the client and server settings.

  -binary body

    The byte-array representation of the given Tcl object will be used as the response body. No character set conversion will be done.

  -file filepath

    The file identified by the given filepath will be sent as the response body. The bytes of the file will not be transformed in any way.

  -fileid channel

    The file identified by the given Tcl channel will be sent as the response body. The bytes of the file will not be transformed in any way.

  -length length

    Specifies the number of bytes to send from the channel.

## EXAMPLES

A traditional geek greeting:

    ns_register_proc GET /hello {
        ns_return 200 text/plain "Hello World!"
    }

A traditional Albanian greeting, using an explicit charset:

    ns_register_proc GET /hello {
        ns_return 200 "text/plain; charset=iso-8859-2" "Përshëndetje të gjithëve!"
    }

## CONFIGURATION

The behavior of the file delivery commands ns_returnfile and ns_respond -file ..., as well as the automatic delivery of static files is influenced by the fastpath settings, which define, how files are served. The fastpath section of the configuration file for a server server1 has a global part (general settings for all servers) and a per (virtual) server part:

       ns_section ns/fastpath
       # global configuration
       ns_param  ...
       ...

       ns_section ns/server/server1/fastpath
       # per-server configuration
       ns_param  ...
       ...

Most prominently, the global fastpath parameters define the delivery mode. In general, fastpath supports three delivery modes for static content:

1. Delivering file via chunk reads from the file, where the chunk size is typical the writersize of a writer thread. This is the same behavior as in ns_respond -fileid ... or in ns_returnfp. This delivery mode is activated, when both the global fastpath parameter cache and mmap are false.

2. Delivering from mapped memory, when when mmap is defined and the operating supports it. In this case the file to be delivered is mapped into memory and served from there. The buffer size etc. is determined from the operating system. This option is activated, when the global fastpath parameter mmap is true and cache is false.

3. Delivering the file from the own NaviServer file cache. This option is activated, when the parameter cache is set to true.

### Global fastpath configuration parameters

cache

  Use the NaviServer file cache for file deliveries (boolean, defaults to false)

cachemaxentry

  Maximum size of a single entry, when parameter cache is true (integer, defaults to 8192)

cachemaxsize

  Size of the cache, when parameter cache is true (integer, defaults to 10240000)

mmap

  Use mmap for file deliveries (and cache is false) (boolean, defaults to false)

gzip_static

  Send the gzip-ed version of the file if available and the client accepts gzip-ed content. When a file path/foo.ext is requested, and there exists a file path/foo.ext.gz, and the timestamp of the gzip-ed file is equal or newer than the source file, use the gzip-ed file for delivery. (boolean, defaults to false)

gzip_refresh

  Refresh gzip file (i.e. re-gzip source) when the modification time of the compressed file is older than the modification time of the source. Note, that the command is just used for re-gzip-ing outdated files; it does not actively compress files, which were previously not compressed (this would be wasteful for e.g. large tmp files, there is not cleanup, etc.). For refreshing gzip files, the Tcl command "::ns_gzipfile source target" is used. This command can be potentially redefined by an application. When this parameter is not defined (or the refresh cmd fails), outdated gzip-ed files are ignored, and a warning is written to the error.log. (boolean, defaults to false)

gzip_cmd

  Command for gzip-ing files, used by ::ns_gzipfile. Teh value of gzip_cmd is used in ::ns_gzipfile to locate the gzip command in the OS. If gzip_cmd is not defined, and ::ns_gzipfile is called, an error is written to the error.log. Example setting: "/usr/bin/gzip -9". (string, defaults to "")

### Per-server fastpath configuration parameters

directoryadp

  Name of an adp page to use to display directory listings. One can either specify directoryadp, or directoryproc, but not both. (string, defaults to "")

directoryfile

  Index files for directory (string, defaults to index.adp index.tcl index.html index.htm)

directorylisting

  Style of directory listings, Can be fancy or simple. (string, defaults to simple)

directoryproc

  Name of Tcl proc to use to display directory listings. One can either specify directoryproc, or directoryadp, but not both. (string, defaults to _ns_dirlist)

hidedotfiles

  Hide files starting with a dot in directory listings (boolean, defaults to false)

pagedir

  Defines absolute or relative path for serving content files. Relative names are relativ to the serverdir (string, defaults to serverdir/pages)

serverdir

  Defines absolute path to server's home directory. (string, defaults to "")

## See Also

ns_adp_puts, ns_conn, ns_guesstype, ns_register, ns_write, ns_writer, returnstatus-cmds

## Keywords

cache, charset, configuration, encoding, fastpath, gzip, mmap, pagedir, response, return, serverdir, status, writer