NaviServer - programmable web server

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

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

## Name

ns_cookie - HTTP cookies

## Table Of Contents

## Synopsis

- ns_setcookie ?-discard bool? ?-domain d? ?-expires t? ?-path p? ?-replace bool? ?-scriptable bool? ?-secure bool? ?--? name data
- ns_getcookie ?-include_set_cookie bool? ?--? name ?default?
- ns_deletecookie ?-domain d? ?-path p? ?-replace bool? ?-secure bool? ?--? name

## Description

Cookies are small pieces of data which the server sends to the user agent and the user agent sends back during subsequent requests. You can use this mechanism to save state between otherwise statelss HTTP requests.

Cookie size limits are user agent dependent. Practically, as cookies are sent with every request to the server (for which the optional domain and path match), size should be kept to a minimum.

These commands implement the original version 1 Netscape cookie protocol which is widely supported by user agents.

## COMMANDS

ns_setcookie ?-discard bool? ?-domain d? ?-expires t? ?-path p? ?-replace bool? ?-scriptable bool? ?-secure bool? ?--? name data

  Send data to the user agent as a cookie, using name as the identifier. The user agent will send the cookie data back to the server during subsequent requests for which the domain and path match, if it has not expired. If the provided domain is empty, it is ignored.

  A cookie is identified by a signature which is made up of it's name, domain, path and secure flag. A cookie named foo with path /x/y is a different cookie than one named foo with path /x/y/z. During a request for the URL /x/y/z both cookies named foo are sent.

  The data will be URL-encoded to escape special characters. ns_getcookie correctly reverses the encoding.

ns_getcookie ?-include_set_cookie bool? ?--? name ?default?

  Get the cookie data identified by name. If no such cookie exists then default is returned. If default is not given and no such cookie exists, an error is raised. When the option -include_set_cookie is set true, then this command will search as well in the cookies being currently set in the output headers.

  Only the first cookie identified by name is returned. If two cookies with the same name are sent by the user agent, each with a different domain and/or path, which cookie data is returned depends on the user agent.

  When using domain or path to restrict cookies, use a unique name for each restricted cookie.

ns_deletecookie ?-domain d? ?-path p? ?-replace bool? ?-secure bool? ?--? name

  Instruct the client to delete the cookie data identified by name. The complete cookie signature including domain and path must match for the cookie to be deleted. If the provided domain is empty, it is ignored.

## OPTIONS

-discard boolean

  If the discard option is true then the cookie will be automaticalled deleted at the end of the current session (when the user agent terminates).

-secure boolean

  If the secure option is true then the the cookie will only be sent back to the server when the client uses a secure (TLS/SSL) connection.

-replace boolean

  If the replace option is true the cookie being set or deleted is as well deleted from the current output header set if provided there. The default value is false.

-scriptable boolean

  If the scriptable option is false or not given the cookie is unavailable to javascript on the client. This can prevent cross site scripting attacks (XSS) on clients which support the HttpOnly option. Set -scriptable to true if you need to access the cookie via javascript.

-domain domain

  Restrict the cookie to a domain name, such as example.com. The current domain is implied if none is specified.

-path path

  Restrict the cookie to a URL path such as /foo/bar. If no path is specified then the cookie will be back sent to the server for all requests. If a path is specified the cookie will only be sent back for requests which match the specified path, or a sub-path.

-expires time

  The cookie will expire in time seconds, after which the client will no longer send the cookie back to the server. If time is large it is treated as the absolute time in the future when the cookie should expire. The special value -1 may be used to indicate that the cookie should never expire.

  The expiry time is valid across browser sessions. If no expiry is specified then the cookie will expire when the browser session ends, which is ususally when the user closes their browser.

## EXAMPLES

Track all user agents which ever vist out site:

    proc browser_tracking_filter {} {
        if {![ns_getcookie first_visit 0]} {
            ns_setcookie -expires -1 -- first_visit [clock seconds]
        }
    }
    ns_register_filter preauth GET /* browser_tracking_filter

## See Also

Ns_Cookie(3), ns_cookiecharset

## Keywords

cookie, session