NaviServer - programmable web server

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

# returnstatus-cmds(n) 4.99.8 naviserver "NaviServer Built-In Commands"

## Name

returnstatus-cmds - Return a complete HTTP status message

## Table Of Contents

## Synopsis

- ns_returnok
- ns_returnmoved url
- ns_returnredirect url
- ns_returnbadrequest reason
- ns_returnunauthorized
- ns_returforbidden
- ns_returnnotfound
- ns_returnunavailable
- ns_returnerror status message
- ns_returnnotice status title message

## Description

These commands return a complete response to the client using a variety of different HTTP status codes. Any queued headers, such as those set by ns_setcookie or manually using ns_conn outputheaders and ns_set put, are added to the default headers and sent in the response.

These commands return 0 (zero) if the response was successfully sent to the client and 1 if the write to the connection failed. They will raise an error if no connection is available, e.g. they are called from a non-connection thread or the response has already been sent and the connection closed.

After the command returns the connection is returned to the driver thread to be closed or monitored for keep-alive. The calling connection thread can then continue to execute code, e.g. to cleanup resources or for logging.

Custom error pages may be specified in the server configuration file to override the default HTML message which is returned, for those commands which return one.

## COMMANDS

ns_returnok

  Return a response with status code 200, OK. No body content is sent.

ns_returnmoved url

  Return a response with status code 301, Moved. A Location header will be set with the given url.

  Use this response to signal that the resource identified by the requested URL has permanently moved to a new location. The client should request the new URL instead of the old one in the future.

ns_returnredirect url

  Return a response with status code 302, Found. The Location header will be set to the url if given.

  Use this response to signal that the resource identified by the requested URL has temporarily moved to a new location. The client should continue to request the old URL.

ns_returnbadrequest reason

  Return a response with status code 400, Bad Request using the given reason in the HTML message.

  Use this response to signal that the client sent a malformed request and should not try again without modifications.

ns_returnunauthorized

  Return a response with status code 401, Access Denied. A WWW-Authenticate header will be set using the realm specified in the configuration file option ns/server:realm.

  Use this response to signal that the user is not authorized to access the URL, and to trigger HTTP basic authorization. The client may present a pop-up window for the user to enter their username and password.

  NB: The username and password will be sent in plain text.

ns_returforbidden

  Return a response with status code 403, Forbidden.

  Use this response to signal that the authentication information the client supplied are insufficient to grant them access to the requested URL.

ns_returnnotfound

  Return a response with status code 404, Not Found.

  Use this response to signal that the content the client requested could not be located given the URL that was requested.

ns_returnunavailable

  Return a response with status code 503, Unavailable.

  Use this response to signal that the server is too busy to deliver the requested resource or is undergoing maintenance.

ns_returnerror status message

  Return a response with the given status code and the error message wrapped in HTML.

  Use this command to return a HTTP status response to the client which is not covered by the above commands, or to customize the HTML message.

ns_returnnotice status title message

  Return a response with the given status code and an HTML message with the given title and message.

  Use this command to return an arbitrary response to the client. Some HTTP responses are expected not to return body content. Check RFC 2616 for details.

  NB: You should be careful what you put in the title and message. It may be tempting to use data which the client has sent you such as a form variable, but it may not be what you expect.

## CONFIGURATION

The body of the response which is returned for a variety of status codes can be customized by registering a new resource which should be returned in it's place. The new resource may be a static, Tcl or ADP page, or a registered procedure or ADP.

    ns_section "ns/server/server1/redirects"
    ns_param   404    /notfound.adp
    ns_param   503    /busy.html

The realm used for HTTP Basic authentication is set server-wide:

    ns_section "ns/server"
    ns_param   realm  "Example"

## EXAMPLES

Use a custom error message to notify users when the hamsters which turn the wheels that run the server are on lunch break:

    ns_register_proc GET /service {
        set hour [clock format [clock seconds] -format %H]
        if {$hour >= 12 && $hour <= 13} {
            ns_returnerror 503 "Gone for lunch. Back at 2pm."
            return
        }
        ns_returnok
    }

## See Also

ns_internalredirect, ns_return

## Keywords

configuration, redirect, response, return, status