NaviServer - programmable web server

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

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

## Name

ns_write - Return data to client

## Table Of Contents

## Synopsis

- ns_headers ?-binary? ?--? status ?mime-type?
- ns_write data ?data ...?
- ns_connsendfp channel length

## Description

These commands are used to manually construct and send a complete HTTP response, or some other non-HTTP response type, to the client.

## COMMANDS

ns_headers ?-binary? ?--? status ?mime-type?

  Set the HTTP response status code and mime-type header for the data which is to be sent. The headers, including any extra headers set via the ns_conn outputheaders command, may not be flushed to the client until the first body data is written.

  The -binary switch indicates that binary data is to be written, in which case the mime-type will be sent as given. Without this switch the mime-type will have the charset for the current connection's encoding appended.

  Returns 0.

ns_write data ?data ...?

  Write all data directly to the client. No HTTP headers are sent unless ns_headers has been called.

  If data is a Tcl byte-array object or the -binary option was given to ns_headers then no transcoding will take place. Otherwise, the encoding in effect for the current connection will be used to encode data.

  If an HTTP response is being constructed (ns_headers has been called) and the client supports it, HTTP chunking will be used to stream data on each call to ns_write. If the client does not support HTTP chunking, connection keep-alive is disabled. Prefer to send a complete response using e.g. ns_return if possible.

  ns_write returns true if all the data was written successfully and false otherwise. On failure, no more writes should be attempted.

  After the command completes the connection remains open and available in the calling connection thread.

ns_connsendfp channel length

  Send length bytes from channel directly to the client. No headers are sent unless ns_headers has been called. No character encoding is done.

  An error is raised if all of length bytes could not be sent or if the channel is invalid.

  After the command completes the connection remains open and available in the calling connection thread.

## EXAMPLES

Report results progressively.

    ns_register_proc GET /long-running-process {
        ns_headers 200 text/plain
        ns_write "Results: \n"
        while {[do_process result]} {
            ns_write "$result\n"
        }
        ns_write "Done."
    }

Sending binary data.

    ns_register_proc GET /blobs {
        ...
        ns_headers -binary -- 200 application/x-whateva
        ns_write $blob1 $blob2
        ...
        ns_write $blob3
    }

## See Also

ns_conn, ns_return

## Keywords

charset, encoding, response, return, status, writer