ns_return - Return a complete HTTP response
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.
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.
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.
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.
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.
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!" }
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:
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.
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.
Delivering the file from the own NaviServer file cache. This option is activated, when the parameter cache is set to true.
Use the NaviServer file cache for file deliveries (boolean, defaults to false)
Maximum size of a single entry, when parameter cache is true (integer, defaults to 8192)
Size of the cache, when parameter cache is true (integer, defaults to 10240000)
Use mmap for file deliveries (and cache is false) (boolean, defaults to false)
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)
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)
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 "")
Name of an adp page to use to display directory listings. One can either specify directoryadp, or directoryproc, but not both. (string, defaults to "")
Index files for directory (string, defaults to index.adp index.tcl index.html index.htm)
Style of directory listings, Can be fancy or simple. (string, defaults to simple)
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)
Hide files starting with a dot in directory listings (boolean, defaults to false)
Defines absolute or relative path for serving content files. Relative names are relativ to the serverdir (string, defaults to serverdir/pages)
Defines absolute path to server's home directory. (string, defaults to "")