Mercurial > hg > nginx-site

view xml/en/docs/njs/reference.xml @ 2667:2085eb315672

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated description of s.send in njs Reference.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 04 Mar 2021 16:38:00 +0000
parents 68c0566a375f
children e067ad74b0cd
line wrap: on
line source

<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">

<article name="Reference"
        link="/en/docs/njs/reference.html"
        lang="en"
        rev="65">

<section id="summary">

<para>
<link doc="index.xml">njs</link> provides objects, methods and properties
for extending nginx functionality.
</para>

<para>
This reference contains only njs specific properties, methods and modules
not compliant with ECMAScript.
Definitions of njs properties and methods compliant with ECMAScript
can be found in
<link url="http://www.ecma-international.org/ecma-262/">ECMAScript
specification</link>.
List of all njs properties and methods can be found in
<link doc="compatibility.xml">Compatibility</link>.
</para>

</section>


<section id="http_stream" name="nginx objects">


<section id="http" name="HTTP Request">

<para>
The HTTP request object is available only in the
<link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> module.
All string properties of the object are
<link id="string">byte strings</link>.

<list type="tag">

<tag-name id="r_args"><literal>r.args{}</literal></tag-name>
<tag-desc>
request arguments object, read-only
</tag-desc>

<tag-name id="r_done"><literal>r.done()</literal></tag-name>
<tag-desc>
after calling this function,
next data chunks will be passed to client without calling
<link doc="../http/ngx_http_js_module.xml" id="js_body_filter"/>
(<link doc="changes.xml" id="njs0.5.2">0.5.2</link>).
May be called only from the
<link doc="../http/ngx_http_js_module.xml" id="js_body_filter"/> function
</tag-desc>

<tag-name id="r_error"><literal>r.error(<value>string</value>)</literal></tag-name>
<tag-desc>
writes a <literal>string</literal> to the error log
on the <literal>error</literal> level of logging
</tag-desc>

<tag-name id="r_finish"><literal>r.finish()</literal></tag-name>
<tag-desc>
finishes sending a response to the client
</tag-desc>

<tag-name id="r_headers_in"><literal>r.headersIn{}</literal></tag-name>
<tag-desc>
incoming headers object, read-only.
<para>
The <literal>Foo</literal> request header
can be accessed with the syntax:
<literal>headersIn.foo</literal> or <literal>headersIn['Foo']</literal>.
</para>

<para>
The 
<header>Authorization</header>,
<header>Content-Length</header>,
<header>Content-Range</header>,
<header>Content-Type</header>,
<header>ETag</header>,
<header>Expect</header>,
<header>From</header>,
<header>Host</header>,
<header>If-Match</header>,
<header>If-Modified-Since</header>,
<header>If-None-Match</header>,
<header>If-Range</header>,
<header>If-Unmodified-Since</header>,
<header>Max-Forwards</header>,
<header>Proxy-Authorization</header>,
<header>Referer</header>,
<header>Transfer-Encoding</header>, and
<header>User-Agent</header>
request headers can have only one field value
(<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
Duplicate field values in <header>Cookie</header> headers
are separated by semicolon (<literal>;</literal>).
Duplicate field values in all other request headers are separated by commas.
</para>
</tag-desc>

<tag-name id="r_headers_out"><literal>r.headersOut{}</literal></tag-name>
<tag-desc>
outgoing headers object, writable.
<para>
The <header>Foo</header> response header
can be accessed with the syntax:
<literal>headersOut.foo</literal> or <literal>headersOut['Foo']</literal>.
</para>

<para>
Field values of multi-value response headers
(<link doc="changes.xml" id="njs0.4.0">0.4.0</link>)
can be set with the syntax:
<example>
r.headersOut['Foo'] = ['a', 'b']
</example>
where the output will be:
<example>
Foo: a
Foo: b
</example>
All previous field values of the <header>Foo</header> response header
will be deleted.
</para>

<para>
For standard response headers
that accept only a single field value such as
<header>Content-Type</header>,
only the last element of the array will take effect.
Field values of the <header>Set-Cookie</header> response header
are always returned as an array.
Duplicate field values in
<header>Age</header>,
<header>Content-Encoding</header>,
<header>Content-Length</header>,
<header>Content-Type</header>,
<header>ETag</header>,
<header>Expires</header>,
<header>Last-Modified</header>,
<header>Location</header>,
<header>Retry-After</header>
response headers are ignored.
Duplicate field values in all other response headers
are separated by commas.
</para>
</tag-desc>

<tag-name id="r_http_version"><literal>r.httpVersion</literal></tag-name>
<tag-desc>
HTTP version, read-only
</tag-desc>

<tag-name id="r_internal_redirect"><literal>r.internalRedirect(<value>uri</value>)</literal></tag-name>
<tag-desc>
performs an internal redirect to the specified <literal>uri</literal>.
If the uri starts with the “<literal>@</literal>” prefix,
it is considered a named location.
The actual redirect happens after the handler execution is completed.
</tag-desc>

<tag-name id="r_log"><literal>r.log(<value>string</value>)</literal></tag-name>
<tag-desc>
writes a <literal>string</literal> to the error log
on the <literal>info</literal> level of logging
</tag-desc>

<tag-name id="r_method"><literal>r.method</literal></tag-name>
<tag-desc>
HTTP method, read-only
</tag-desc>

<tag-name id="r_parent"><literal>r.parent</literal></tag-name>
<tag-desc>
references the parent request object
</tag-desc>

<tag-name id="r_remote_address"><literal>r.remoteAddress</literal></tag-name>
<tag-desc>
client address, read-only
</tag-desc>

<tag-name id="r_request_body"><literal>r.requestBody</literal></tag-name>
<tag-desc>
the property is deprecated since
<link doc="changes.xml" id="njs0.5.0">0.5.0</link>,
the <link id="r_request_buffer"><literal>r.requestBuffer</literal></link> or
<link id="r_request_text"><literal>r.requestText</literal></link> property
should be used instead.
</tag-desc>

<tag-name id="r_request_buffer"><literal>r.requestBuffer</literal></tag-name>
<tag-desc>
client request body if it has not been written to a temporary file
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
To ensure that the client request body is in memory,
its size should be limited by
<link doc="../http/ngx_http_core_module.xml" id="client_max_body_size"/>,
and a sufficient buffer size should be set using
<link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/>.
The property is available only in the
<link doc="../http/ngx_http_js_module.xml" id="js_content"/> directive.
</tag-desc>

<tag-name id="r_request_text"><literal>r.requestText</literal></tag-name>
<tag-desc>
the same as <link id="r_request_buffer"><literal>r.requestBuffer</literal></link>,
but returns a <literal>string</literal>.
Note that
it may convert bytes invalid in utf8 encoding into the replacement character.
</tag-desc>

<tag-name id="r_raw_headers_in"><literal>r.rawHeadersIn{}</literal></tag-name>
<tag-desc>
returns an array of key-value pairs
exactly as they were received from the client
(<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
<para>
For example, with the following request headers:
<example>
Host: localhost
Foo:  bar
foo:  bar2
</example>
the output of <literal>r.rawHeadersIn</literal> will be:
<example>
[
    ['Host', 'localhost'],
    ['Foo', 'bar'],
    ['foo', 'bar2']
]
</example>
All <literal>foo</literal> headers
can be collected with the syntax:
<example>
r.rawHeadersIn.filter(v=>v[0].toLowerCase() == 'foo').map(v=>v[1])
</example>
the output will be:
<example>
['bar', 'bar2']
</example>
Header field names are not converted to lower case,
duplicate field values are not merged.
</para>
</tag-desc>

<tag-name id="r_raw_headers_out"><literal>r.rawHeadersOut{}</literal></tag-name>
<tag-desc>
returns an array of key-value pairs of response headers
(<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
Header field names are not converted to lower case,
duplicate field values are not merged.
</tag-desc>

<tag-name id="r_response_body"><literal>r.responseBody</literal></tag-name>
<tag-desc>
the property is deprecated since
<link doc="changes.xml" id="njs0.5.0">0.5.0</link>,
the <link id="r_response_buffer"><literal>r.responseBuffer</literal></link>
or
the <link id="r_response_text"><literal>r.responseText</literal></link>
property
should be used instead.
</tag-desc>

<tag-name id="r_response_buffer"><literal>r.responseBuffer</literal></tag-name>
<tag-desc>
holds the <link id="r_subrequest">subrequest</link> response body,
read-only
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
The size of <literal>r.responseBuffer</literal> is limited by the
<link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/>
directive.
</tag-desc>

<tag-name id="r_response_text"><literal>r.responseText</literal></tag-name>
<tag-desc>
the same as <link id="r_response_buffer"><literal>r.responseBuffer</literal></link>
but returns a string
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
Note that
it may convert bytes invalid in utf8 encoding into the replacement character.
</tag-desc>

<tag-name id="r_return"><literal>r.return(status[,
string | Buffer])</literal></tag-name>
<tag-desc>
sends the entire response
with the specified <literal>status</literal> to the client.
The response can be a string or Buffer
(<link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
<para>
It is possible to specify either a redirect URL
(for codes 301, 302, 303, 307, and 308)
or the response body text (for other codes) as the second argument
</para>
</tag-desc>

<tag-name id="r_send"><literal>r.send(string
| Buffer)</literal></tag-name>
<tag-desc>
sends a part of the response body to the client.
The data sent can be a string or Buffer
(<link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
</tag-desc>

<tag-name id="r_sendbuffer"><literal>r.sendBuffer(<value>data</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
adds data to the chain of data chunks to be forwarded to the next body filter
(<link doc="changes.xml" id="njs0.5.2">0.5.2</link>).
The actual forwarding happens later,
when the all the data chunks of the current chain are processed.
<para>
The data can be a string or Buffer.
The <literal>options</literal> is an object used
to override nginx buffer flags derived from an incoming data chunk buffer.
The flags can be overridden with the following flags:
<list type="tag">

<tag-name><literal>last</literal></tag-name>
<tag-desc>
boolean,
true if the buffer is the last buffer
</tag-desc>

<tag-name><literal>flush</literal></tag-name>
<tag-desc>
boolean,
true if the buffer should have the <literal>flush</literal> flag
</tag-desc>
</list>
</para>
The method may be called only from the
<link doc="../http/ngx_http_js_module.xml" id="js_body_filter"/> function.
</tag-desc>

<tag-name id="r_send_header"><literal>r.sendHeader()</literal></tag-name>
<tag-desc>
sends the HTTP headers to the client
</tag-desc>

<tag-name id="r_status"><literal>r.status</literal></tag-name>
<tag-desc>
status, writable
</tag-desc>

<tag-name id="r_subrequest"><literal>r.subrequest(<value>uri</value>[,
<value>options</value>[, <value>callback</value>]])</literal></tag-name>
<tag-desc>
creates a subrequest with the given <literal>uri</literal> and
<literal>options</literal>, and installs
an optional completion <literal>callback</literal>.

<para>
A
<link doc="../dev/development_guide.xml.xml" id="http_subrequests">subrequest</link>
shares its input headers with the client request.
To send headers different from original headers to a proxied server, the
<link doc="../http/ngx_http_proxy_module.xml" id="proxy_set_header"/>
directive can be used.
To send a completely new set of headers to a proxied server, the
<link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass_request_headers"/>
directive can be used.
</para>

<para>
If <literal>options</literal> is a string, then it
holds the subrequest arguments string.
Otherwise, <literal>options</literal> is expected to be
an object with the following keys:
<list type="tag">
<tag-name><literal>args</literal></tag-name>
<tag-desc>
arguments string, by default an empty string is used
</tag-desc>
<tag-name><literal>body</literal></tag-name>
<tag-desc>
request body,
by default the request body of the parent request object is used
</tag-desc>

<tag-name><literal>method</literal></tag-name>
<tag-desc>
HTTP method, by default the <literal>GET</literal> method is used
</tag-desc>

<tag-name><literal>detached</literal></tag-name>
<tag-desc>
boolean flag (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>),
if <literal>true</literal>, the created subrequest is a detached subrequest.
Responses to detached subrequests are ignored.
Unlike ordinary subrequests, a detached subrequest
can be created inside a variable handler.
The <literal>detached</literal> flag and callback argument
are mutually exclusive.
</tag-desc>

</list>
</para>

<para>
The completion <literal>callback</literal> receives
a subrequest response object with methods and properties
identical to the parent request object.
</para>

<para>
Since <link doc="changes.xml" id="njs0.3.8">0.3.8</link>,
if a <literal>callback</literal> is not provided,
the <literal>Promise</literal> object
that resolves to the subrequest response object is returned.
</para>
</tag-desc>

<tag-name id="r_uri"><literal>r.uri</literal></tag-name>
<tag-desc>
current <link doc="../http/ngx_http_core_module.xml" id="var_uri">URI</link>
in request,
<link doc="../http/ngx_http_core_module.xml" id="location">normalized</link>,
read-only
</tag-desc>

<tag-name id="r_raw_variables"><literal>r.rawVariables{}</literal></tag-name>
<tag-desc>
nginx <link id="r_variables">variables</link> as Buffers,
writable
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
</tag-desc>

<tag-name id="r_variables"><literal>r.variables{}</literal></tag-name>
<tag-desc>
nginx variables object, writable
(since <link doc="changes.xml" id="njs0.2.8">0.2.8</link>)
</tag-desc>

<tag-name id="r_warn"><literal>r.warn(<value>string</value>)</literal></tag-name>
<tag-desc>
writes a <literal>string</literal> to the error log
on the <literal>warning</literal> level of logging
</tag-desc>

</list>
</para>

</section>


<section id="stream" name="Stream Session">

<para>
The stream session object is available only in the
<link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link>
module.
All string properties of the object are <link id="string">byte strings</link>.
</para>

<para>
<list type="tag">

<tag-name id="s_allow"><literal>s.allow()</literal></tag-name>
<tag-desc>
successfully finalizes the phase handler
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>)
</tag-desc>

<tag-name id="s_decline"><literal>s.decline()</literal></tag-name>
<tag-desc>
finalizes the phase handler and passes control to the next handler
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>)
</tag-desc>

<tag-name id="s_deny"><literal>s.deny()</literal></tag-name>
<tag-desc>
finalizes the phase handler with the access error code
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>)
</tag-desc>

<tag-name id="s_done"><literal>s.done</literal>(<value>[code]</value>)</tag-name>
<tag-desc>
successfully finalizes the current phase handler
or finalizes it with the specified numeric code
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>).
</tag-desc>

<tag-name id="s_error"><literal>s.error(<value>string</value>)</literal></tag-name>
<tag-desc>
writes a sent <literal>string</literal> to the error log
on the <literal>error</literal> level of logging
</tag-desc>

<tag-name id="s_log"><literal>s.log(<value>string</value>)</literal></tag-name>
<tag-desc>
writes a sent <value>string</value> to the error log
on the <literal>info</literal> level of logging
</tag-desc>

<tag-name id="s_off"><literal>s.off(<value>eventName</value>)</literal></tag-name>
<tag-desc>
unregisters the callback set by the <link id="s_on">s.on()</link> method
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>)
</tag-desc>

<tag-name id="s_on"><literal>s.on(<value>event</value>,
<value>callback</value>)</literal></tag-name>
<tag-desc>
registers a <literal>callback</literal>
for the specified <literal>event</literal>
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>).

<para>
An <literal>event</literal> may be one of the following strings:
<list type="tag">
<tag-name><literal>upload</literal></tag-name>
<tag-desc>
new data (string) from a client
</tag-desc>

<tag-name><literal>download</literal></tag-name>
<tag-desc>
new data (string) to a client
</tag-desc>

<tag-name><literal>upstream</literal></tag-name>
<tag-desc>
new data (Buffer) from a client
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
</tag-desc>

<tag-name><literal>downstream</literal></tag-name>
<tag-desc>
new data (Buffer) to a client
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
</tag-desc>

</list>
</para>

<para>
The completion callback has the following prototype:
<literal>callback(data, flags)</literal>, where
<literal>data</literal> is string or Buffer (depending on the event type)
<literal>flags</literal> is an object
with the following properties:
<list type="tag">
<tag-name id="s_on_callback_last"><literal>last</literal></tag-name>
<tag-desc>
a boolean value, true if data is a last buffer.
</tag-desc>

</list>
</para>
</tag-desc>

<tag-name id="s_remote_address"><literal>s.remoteAddress</literal></tag-name>
<tag-desc>
client address, read-only
</tag-desc>

<tag-name id="s_raw_variables"><literal>s.rawVariables</literal></tag-name>
<tag-desc>
nginx <link id="s_variables">variables</link> as Buffers,
writable
(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
</tag-desc>

<tag-name id="s_send"><literal>s.send(<value>data</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
adds data to the chain of data chunks that will be forwarded in
the forward direction:
in download callback to a client; in upload to an upstream server
(<link doc="changes.xml" id="njs0.2.4">0.2.4</link>).
The actual forwarding happens later,
when the all the data chunks of the current chain are processed.
<para>
The data can be a string or Buffer
(<link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
The <literal>options</literal> is an object used
to override nginx buffer flags derived from an incoming data chunk buffer.
The flags can be overridden with the following flags:
<list type="tag">

<tag-name><literal>last</literal></tag-name>
<tag-desc>
boolean,
true if the buffer is the last buffer
</tag-desc>

<tag-name><literal>flush</literal></tag-name>
<tag-desc>
boolean,
true if the buffer should have the <literal>flush</literal> flag
</tag-desc>
</list>
</para>
The method can be called multiple times per callback invocation.
</tag-desc>

<tag-name id="s_status"><literal>s.status</literal></tag-name>
<tag-desc>
session status code, an alias to the
<link doc="../stream/ngx_stream_core_module.xml" id="var_status"><literal>$status</literal></link>
variable,
read only
(since <link doc="changes.xml" id="njs0.5.2">0.5.2</link>)
</tag-desc>

<tag-name id="s_variables"><literal>s.variables{}</literal></tag-name>
<tag-desc>
nginx variables object, writable
(since <link doc="changes.xml" id="njs0.2.8">0.2.8</link>)
</tag-desc>

<tag-name id="s_warn"><literal>s.warn(<value>string</value>)</literal></tag-name>
<tag-desc>
writes a sent <literal>string</literal> to the error log
on the <literal>warning</literal> level of logging
</tag-desc>

</list>
</para>

</section>


<section id="response" name="Response">

<para>
The <literal>Response</literal> interface is available since
<link doc="changes.xml" id="njs0.5.1">0.5.1</link>.

<list type="tag">

<tag-name id="response_arraybuffer"><literal>arrayBuffer()</literal></tag-name>
<tag-desc>
Takes a <literal>Response</literal> stream and reads it to completion.
Returns a <literal>Promise</literal> that resolves with
an <literal>ArrayBuffer</literal>.
</tag-desc>

<tag-name id="response_bodyused"><literal>bodyUsed</literal></tag-name>
<tag-desc>
A boolean value, <literal>true</literal>
if the body was read.
</tag-desc>

<tag-name id="response_headers"><literal>headers</literal></tag-name>
<tag-desc>
The <literal>Headers</literal> read-only object associated with the
<link id="global_response"><literal>Response</literal></link>:

<list type="tag">

<tag-name id="headers_get"><literal>get(<value>name</value>)</literal></tag-name>
<tag-desc>
returns a string containing the values of all headers with the specified name
separated by a comma and a space
</tag-desc>

<tag-name id="headers_getall"><literal>getAll(<value>name</value>)</literal></tag-name>
<tag-desc>
returns an array containing the values of all headers with the specified name
</tag-desc>

<tag-name id="headers_has"><literal>has(<value>name</value>)</literal></tag-name>
<tag-desc>
returns a boolean value
indicating whether a header with the specified name exists
</tag-desc>

</list>
</tag-desc>

<tag-name id="response_json"><literal>json()</literal></tag-name>
<tag-desc>
Takes a <literal>Response</literal> stream and reads it to completion.
Returns a <literal>Promise</literal> that resolves with
the result of parsing the body text as JSON.
</tag-desc>

<tag-name id="response_ok"><literal>ok</literal></tag-name>
<tag-desc>
A boolean value, <literal>true</literal>
if the response was successful (status codes between 200–299).
</tag-desc>

<tag-name id="response_redirect"><literal>redirected</literal></tag-name>
<tag-desc>
A boolean value, <literal>true</literal>
if the response is the result of a redirect.
</tag-desc>

<tag-name id="response_status"><literal>status</literal></tag-name>
<tag-desc>
The status code of the response.
</tag-desc>

<tag-name id="response_statustext"><literal>statusText</literal></tag-name>
<tag-desc>
The status message corresponding to the status code.
</tag-desc>

<tag-name id="response_text"><literal>text()</literal></tag-name>
<tag-desc>
Takes a <literal>Response</literal> stream and reads it to completion.
Returns a <literal>Promise</literal> that resolves with a string.
</tag-desc>

<tag-name id="response_type"><literal>type</literal></tag-name>
<tag-desc>
The type of the response.
</tag-desc>

<tag-name id="response_url"><literal>url</literal></tag-name>
<tag-desc>
The URL of the response.
</tag-desc>

</list>
</para>

</section>


<section id="ngx" name="ngx">

<para>
The <literal>ngx</literal> global object is available
since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>.
<list type="tag">

<tag-name id="ngx_fetch"><literal>ngx.fetch(<value>url</value>,
[<value>options</value>])</literal></tag-name>
<tag-desc>
Makes a request to fetch an URL
(<link doc="changes.xml" id="njs0.5.1">0.5.1</link>),
returns a <literal>Promise</literal> that resolves with
the <link id="global_response"><literal>Response</literal></link> object.
Only the <literal>http://</literal> scheme is supported,
redirects are not handled.
<para>
The <literal>options</literal> parameter is expected to be an object
with the following keys:
<list type="tag">

<tag-name id="fetch_body"><literal>body</literal></tag-name>
<tag-desc>
request body,
by default is empty
</tag-desc>

<tag-name id="fetch_buffer_size"><literal>buffer_size</literal></tag-name>
<tag-desc>
the buffer size for reading the response,
by default is <literal>4096</literal>
</tag-desc>

<tag-name id="fetch_headers"><literal>headers</literal></tag-name>
<tag-desc>
request headers object
</tag-desc>

<tag-name id="fetch_get"><literal>max_response_body_size</literal></tag-name>
<tag-desc>
the maximum size of the response body in bytes,
by default is <literal>32768</literal>
</tag-desc>

<tag-name id="fetch_method"><literal>method</literal></tag-name>
<tag-desc>
HTTP method,
by default the <literal>GET</literal> method is used
</tag-desc>

</list>
Example:
<example>
ngx.fetch('http://nginx.org/')
.then(reply => reply.text())
.then(body => r.return(200, body))
.catch(e => r.return(501, e.message))
</example>
</para>
</tag-desc>

<tag-name id="ngx_log"><literal>ngx.log</literal>(<value>level</value>,
<value>message</value>)</tag-name>
<tag-desc>
Writes a message to the error log with the specified level of logging.
The <value>level</value> parameter specifies one of the log levels,
the <value>message</value> parameter can be a string or Buffer.
The following log levels can be specified:
<literal>ngx.INFO</literal>,
<literal>ngx.WARN</literal>, and
<literal>ngx.ERR</literal>.
</tag-desc>

</list>
</para>

</section>

</section>


<section id="core" name="Core">


<section id="core_global" name="Global">


<section id="njs" name="njs">

<para>
The <literal>njs</literal> object is a global object
that represents the current VM instance
(since <link doc="changes.xml" id="njs0.2.0">0.2.0</link>).
</para>

<para>
<list type="tag">

<tag-name id="njs_version"><literal>njs.version</literal></tag-name>
<tag-desc>
Returns a string with the current version of njs
(for example, “0.5.2”).
</tag-desc>

<tag-name id="njs_dump"><literal>njs.dump(<value>value</value>)</literal></tag-name>
<tag-desc>
Returns the pretty-print string representation for a value.
</tag-desc>

<tag-name id="njs_on"><literal>njs.on</literal></tag-name>
<tag-desc>
Registers a callback for the specified VM event
(since <link doc="changes.xml" id="njs0.5.2">0.5.2</link>).
An event may be one of the following strings:
<list type="tag">

<tag-name><literal>exit</literal></tag-name>
<tag-desc>
is called before the VM is destroyed.
The callback is called without arguments.
</tag-desc>

</list>
</tag-desc>

</list>
</para>

</section>


<section id="process" name="Process">

<para>
The <literal>process</literal> object is a global object
that provides information about the current process
(<link doc="changes.xml" id="njs0.3.3">0.3.3</link>).
</para>

<para>
<list type="tag">

<tag-name id="process_argv"><literal>process.argv</literal></tag-name>
<tag-desc>
Returns an array that contains the command line arguments
passed when the current process was launched.
</tag-desc>

<tag-name id="process_env"><literal>process.env</literal></tag-name>
<tag-desc>
Returns an object containing the user environment.
<note>
By default, nginx removes all environment variables inherited
from its parent process except the TZ variable.
Use the <link doc="../ngx_core_module.xml" id="env"/> directive
to preserve some of the inherited variables.
</note>
</tag-desc>

<tag-name id="process_pid"><literal>process.pid</literal></tag-name>
<tag-desc>
Returns the PID of the current process.
</tag-desc>

<tag-name id="process_ppid"><literal>process.ppid</literal></tag-name>
<tag-desc>
Returns the PID of the current parent process.
</tag-desc>

</list>
</para>

</section>

</section>


<section id="string" name="String">

<para>
There are two types of strings in njs: a Unicode string (default) and
a byte string.
</para>

<para>
A Unicode string corresponds to an ECMAScript string
which contains Unicode characters.
</para>

<para>
Byte strings contain a sequence of bytes
and are used to serialize Unicode strings
to external data and deserialize from external sources.
For example, the <link id="string_toutf8">toUTF8()</link> method serializes
a Unicode string to a byte string using UTF8 encoding:
<example>
>> '£'.toUTF8().toString('hex')
'c2a3'  /* C2 A3 is the UTF8 representation of 00A3 ('£') code point */
</example>
The <link id="string_tobytes">toBytes()</link> method serializes
a Unicode string with code points up to 255 into a byte string,
otherwise, <literal>null</literal> is returned:
<example>
>> '£'.toBytes().toString('hex')
'a3'  /* a3 is a byte equal to 00A3 ('£') code point  */
</example>

<list type="tag">

<tag-name id="string_bytesfrom"><literal>String.bytesFrom(<value>array</value>
| <value>string</value>, <value>encoding</value>)</literal></tag-name>
<tag-desc>
Creates a byte string either from an array that contains octets,
or from an encoded string
(<link doc="changes.xml" id="njs0.2.3">0.2.3</link>).
The encoding can be
<literal>hex</literal>,
<literal>base64</literal>, and
<literal>base64url</literal>.
The method is deprecated since
<link doc="changes.xml" id="njs0.4.4">0.4.4</link>,
the <literal>Buffer.from</literal> method should be used instead:
<example>
>> Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]).toString()
'buffer'

>> Buffer.from('YnVmZmVy', 'base64').toString()
'buffer'
</example>
</tag-desc>

<tag-name id="string_frombytes"><literal>String.prototype.fromBytes(<value>start</value>[,
<value>end</value>])</literal></tag-name>
<tag-desc>
Returns a new Unicode string from a byte string
where each byte is replaced with a corresponding Unicode code point.
</tag-desc>

<tag-name id="string_fromutf8"><literal>String.prototype.fromUTF8(<value>start</value>[,
<value>end</value>])</literal></tag-name>
<tag-desc>
Converts a byte string containing a valid UTF8 string
into a Unicode string,
otherwise <literal>null</literal> is returned.
</tag-desc>

<tag-name id="string_tobytes"><literal>String.prototype.toBytes(<value>start</value>[,
<value>end</value>])</literal></tag-name>
<tag-desc>
Serializes a Unicode string to a byte string.
Returns <literal>null</literal> if a character larger than 255 is
found in the string.
</tag-desc>

<tag-name id="string_tostring"><literal>String.prototype.toString(<value>encoding</value>)</literal></tag-name>
<tag-desc>
<para>
Encodes a string to
<literal>hex</literal>,
<literal>base64</literal>, or
<literal>base64url</literal>:
<example>
>>  'αβγδ'.toString('base64url')
'zrHOss6zzrQ'
</example>
Before version <link doc="changes.xml" id="njs0.4.3">0.4.3</link>,
only a <link id="string_tobytes">byte string</link> could be encoded:
<example>
>>  'αβγδ'.toUTF8().toString('base64url')
'zrHOss6zzrQ'
</example>
</para>
</tag-desc>

<tag-name id="string_toutf8"><literal>String.prototype.toUTF8(<value>start</value>[,
<value>end</value>])</literal></tag-name>
<tag-desc>
Serializes a Unicode string
to a byte string using UTF8 encoding.
<example>
>> 'αβγδ'.toUTF8().length
8
>> 'αβγδ'.length
4
</example>
</tag-desc>

</list>
</para>

</section>


<section id="textdecoder" name="Text Decoder">

<para>
The <literal>TextDecoder</literal>
produces a stream of code points
from a stream of bytes
(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
</para>

<para>
<list type="tag">

<tag-name><literal>TextDecoder([[<value>encoding</value>],
<value>options</value>])</literal></tag-name>
<tag-desc>
Creates a new <literal>TextDecoder</literal> object
for specified <literal>encoding</literal>,
currently, only UTF-8 is supported.
The <literal>options</literal> is
<literal>TextDecoderOptions</literal> dictionary with the property:

<list type="tag">

<tag-name><literal>fatal</literal></tag-name>
<tag-desc>
boolean flag indicating if
<link id="textdecoder_decode"><literal>TextDecoder.decode()</literal></link>
must throw the <value>TypeError</value> exception when
a coding error is found, by default is <literal>false</literal>.
</tag-desc>

</list>
</tag-desc>

<tag-name id="textdecoder_encoding"><literal>TextDecoder.prototype.encoding</literal></tag-name>
<tag-desc>
Returns a string with the name of the encoding used by
<link id="textdecoder"><literal>TextDecoder()</literal></link>,
read-only.
</tag-desc>

<tag-name id="textdecoder_fatal"><literal>TextDecoder.prototype.fatal</literal></tag-name>
<tag-desc>
boolean flag, <literal>true</literal> if
the error mode is fatal,
read-only.
</tag-desc>

<tag-name id="textdecoder_ignorebom"><literal>TextDecoder.prototype.ignoreBOM</literal></tag-name>
<tag-desc>
boolean flag, <literal>true</literal> if
the byte order marker is ignored,
read-only.
</tag-desc>

<tag-name id="textdecoder_decode"><literal>TextDecoder.prototype.decode(<value>buffer</value>,
[<value>options</value>])</literal></tag-name>
<tag-desc>
Returns a string with the text
decoded from the <literal>buffer</literal> by
<link id="textdecoder"><literal>TextDecoder()</literal></link>.
The buffer can be <literal>ArrayBuffer</literal>.
The <literal>options</literal> is
<literal>TextDecodeOptions</literal> dictionary with the property:

<list type="tag">

<tag-name><literal>stream</literal></tag-name>
<tag-desc>
boolean flag indicating if
additional data will follow in subsequent calls to <literal>decode()</literal>:
<literal>true</literal> if processing the data in chunks, and
<literal>false</literal> for the final chunk
or if the data is not chunked.
By default is <literal>false</literal>.
</tag-desc>

</list>
<example>
>> (new TextDecoder()).decode(new Uint8Array([206,177,206,178]))
αβ
</example>
</tag-desc>

</list>
</para>

</section>


<section id="textencoder" name="Text Encoder">

<para>
The <literal>TextEncoder</literal> object
produces a byte stream with UTF-8 encoding
from a stream of code points
(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
</para>

<para>
<list type="tag">

<tag-name><literal>TextEncoder()</literal></tag-name>
<tag-desc>
Returns a newly constructed <literal>TextEncoder</literal>
that will generate a byte stream with UTF-8 encoding.
</tag-desc>

<tag-name id="textencoder_encode"><literal>TextEncoder.prototype.encode(<value>string</value>)</literal></tag-name>
<tag-desc>
Encodes <literal>string</literal> into a <literal>Uint8Array</literal>
with UTF-8 encoded text.
</tag-desc>

<tag-name id="textencoder_encodeinto"><literal>TextEncoder.prototype.encodeInto(<value>string</value>,
<value>uint8Array</value>)</literal></tag-name>
<tag-desc>
Encodes a <literal>string</literal> to UTF-8,
puts the result into destination <literal>Uint8Array</literal>, and
returns a dictionary object that shows the progress of the encoding.
The dictionary object contains two members:

<list type="tag">

<tag-name><literal>read</literal></tag-name>
<tag-desc>
the number of UTF-16 units of code from the source <literal>string</literal>
converted to UTF-8
</tag-desc>

<tag-name><literal>written</literal></tag-name>
<tag-desc>
the number of bytes modified in the destination <literal>Uint8Array</literal>
</tag-desc>

</list>
</tag-desc>

</list>
</para>

</section>


<section id="njs_api_timers" name="Timers">

<para>
<list type="tag">

<tag-name id="cleartimeout"><literal>clearTimeout(<value>timeout</value>)</literal></tag-name>
<tag-desc>
Cancels a <literal>timeout</literal> object
created by <link id="settimeout"><literal>setTimeout()</literal></link>.
</tag-desc>

<tag-name id="settimeout"><literal>setTimeout(<value>function</value>,
<value>milliseconds</value>[,
<value>argument1</value>,
<value>argumentN</value>])</literal></tag-name>
<tag-desc>
Calls a <literal>function</literal>
after a specified number of <literal>milliseconds</literal>.
One or more optional <literal>arguments</literal>
can be passed to the specified function.
Returns a <literal>timeout</literal> object.
<example>
function handler(v)
{
    // ...
}

t = setTimeout(handler, 12);

// ...

clearTimeout(t);
</example>
</tag-desc>

</list>
</para>

</section>

</section>


<section id="built-in" name="Built-in Modules">


<section id="buffer" name="Buffer">

<para>
<list type="tag">

<tag-name id="buffer_alloc"><literal>Buffer.alloc(<value>size</value>[,
<value>fill</value>[,
<value>encoding</value>]]))</literal></tag-name>
<tag-desc>
<para>
Allocates a new Buffer of a specified <value>size</value>.
If <value>fill</value> is not specified, the Buffer will be zero-filled.
If <value>fill</value> is specified,
the allocated Buffer will be initialized by calling
<link id="buf_fill"><literal>buf.fill(fill)</literal></link>.
If <value>fill</value> and <value>encoding</value> are specified,
the allocated Buffer will be initialized by calling
<link id="buf_fill"><literal>buf.fill(fill,
encoding)</literal></link>.
</para>

<para>
The <value>fill</value> parameter may be a
<value>string</value>,
<value>Buffer</value>,
<value>Uint8Array</value>, or
<value>integer</value>.
</para>
</tag-desc>

<tag-name id="buffer_alloc_unsafe"><literal>Buffer.allocUnsafe(<value>size</value>)</literal></tag-name>
<tag-desc>
<para>
The same as
<link id="buffer_alloc"><literal>Buffer.alloc()</literal></link>,
with the difference that the memory allocated for the buffer is not initialized,
the contents of the new buffer is unknown and may contain sensitive data.
</para>
</tag-desc>

<tag-name id="buffer_bytelength"><literal>Buffer.byteLength(<value>value</value>[,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
Returns the byte length of a specified value,
when encoded using <value>encoding</value>.
The value can be a
<literal>string</literal>,
<literal>Buffer</literal>,
<literal>TypedArray</literal>,
<literal>DataView</literal>, or
<literal>ArrayBuffer</literal>.
If the value is a <value>string</value>,
the <literal>encoding</literal> parameter is its encoding, can be
<value>utf8</value>,
<value>hex</value>,
<value>base64</value>,
<value>base64url</value>;
by default is <value>utf8</value>.
</tag-desc>

<tag-name id="buffer_compare"><literal>Buffer.compare(<value>buffer1</value>,
<value>buffer2</value>)</literal></tag-name>
<tag-desc>
Compares <value>buffer1</value> with <value>buffer2</value>
when sorting arrays of Buffer instances.
Returns
<literal>0</literal> if
<value>buffer1</value> is the same as <value>buffer2</value>,
<literal>1</literal> if
<value>buffer2</value> should come before <value>buffer1</value> when sorted, or
<literal>-1</literal> if
<value>buffer2</value> should come after <value>buffer1</value> when sorted.
</tag-desc>

<tag-name id="buffer_concat"><literal>Buffer.concat(<value>list</value>[,
<value>totalLength</value>])</literal></tag-name>
<tag-desc>
Returns a new Buffer
which is the result of concatenating all the Buffer instances in the list.
If there are no items in the list or the total length is 0, 
a new zero-length Buffer is returned.
If <value>totalLength</value> is not specified,
it is calculated from the Buffer instances in list by adding their lengths.
If <value>totalLength</value> is specified,
it is coerced to an unsigned integer.
If the combined length of the Buffers in list exceeds
<value>totalLength</value>,
the result is truncated to <value>totalLength</value>.
</tag-desc>

<tag-name id="buffer_from_array"><literal>Buffer.from(<value>array</value>)</literal></tag-name>
<tag-desc>
Allocates a new Buffer using an array of bytes
in the range <literal>0</literal> – <literal>255</literal>.
Array entries outside that range will be truncated.
</tag-desc>

<tag-name id="buffer_from_arraybuffer"><literal>Buffer.from(<value>arrayBuffer</value>,
<value>byteOffset</value>[,
<value>length</value>]])</literal></tag-name>
<tag-desc>
Creates a view of the <value>ArrayBuffer</value>
without copying the underlying memory.
The optional <value>byteOffset</value> and <value>length</value> arguments
specify a memory range within the <value>arrayBuffer</value>
that will be shared by the Buffer.
</tag-desc>

<tag-name id="buffer_from_buffer"><literal>Buffer.from(<value>buffer</value>)</literal></tag-name>
<tag-desc>
Copies the passed buffer data onto a new Buffer instance.
</tag-desc>

<tag-name id="buffer_from_object"><literal>Buffer.from(<value>object</value>[,
<value>offsetOrEncoding</value>[,
<value>length</value>]])</literal></tag-name>
<tag-desc>
For objects whose <literal>valueOf()</literal> function
returns a value not strictly equal to object,
returns
<literal>Buffer.from(object.valueOf()</literal>,
<literal>offsetOrEncoding</literal>,
<literal>length</literal>).
</tag-desc>

<tag-name id="buffer_from_string"><literal>Buffer.from(<value>string</value>[,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
Creates a new Buffer with a <value>string</value>.
The <value>encoding</value> parameter identifies the character encoding
to be used when converting a string into bytes.
The encoding can be
<literal>utf8</literal>,
<literal>hex</literal>,
<literal>base64</literal>,
<literal>base64url</literal>;
by default is <literal>utf8</literal>.
</tag-desc>

<tag-name id="buffer_is_buffer"><literal>Buffer.isBuffer(<value>object</value>)</literal></tag-name>
<tag-desc>
A boolean value,
returns <literal>true</literal> if <value>object</value> is a Buffer.
</tag-desc>

<tag-name id="buffer_is_encoding"><literal>Buffer.isEncoding(<value>encoding</value>)</literal></tag-name>
<tag-desc>
A boolean value,
returns <literal>true</literal>
if encoding is the name of a supported character encoding.
</tag-desc>

<tag-name id="buf_index"><literal>buffer[<value>index</value>]</literal></tag-name>
<tag-desc>
The index operator that can be used to get and set the octet
at position <literal>index</literal> in <literal>buffer</literal>.
The values refer to individual bytes,
so the legal value range is between 0 and 255 (decimal).
</tag-desc>

<tag-name id="buf_buffer"><literal>buf.buffer</literal></tag-name>
<tag-desc>
The underlying <literal>ArrayBuffer</literal> object
based on which this Buffer object is created.
</tag-desc>

<tag-name id="buf_byte_offset"><literal>buf.byteOffset</literal></tag-name>
<tag-desc>
An integer,
specifying the <literal>byteOffset</literal> of the Buffers
underlying <literal>ArrayBuffer</literal> object.
</tag-desc>

<tag-name id="buf_compare"><literal>buf.compare(<value>target</value>[,
<value>targetStart</value>[,
<value>targetEnd</value>[,
<value>sourceStart</value>[,
<value>sourceEnd</value>]]]])</literal></tag-name>
<tag-desc>
Compares buffer with <value>target</value> and returns a number
indicating whether buffer comes before, after, or is the same
as <value>target</value> in sort order.
Comparison is based on the actual sequence of bytes in each Buffer.
The <literal>targetStart</literal> is an integer specifying
the offset within <value>target</value> at which to begin comparison,
by default is 0.
The <literal>targetEnd</literal> is an integer specifying
the offset within <value>target</value> at which to end comparison,
by default is <literal>target.length</literal>.
The <literal>sourceStart</literal> is an integer specifying
the offset within buffer at which to begin comparison,
by default is 0.
The <literal>sourceEnd</literal> is an integer specifying
the offset within buffer at which to end comparison (not inclusive),
by default is <literal>buf.length</literal>.
</tag-desc>

<tag-name id="buf_copy"><literal>buf.copy(<value>target</value>[,
<value>targetStart</value>[,
<value>sourceStart</value>[,
<value>sourceEnd</value>]]])</literal></tag-name>
<tag-desc>
Copies data from a region of buffer to a region in <value>target</value>,
even if the target memory region overlaps with buffer.
The <literal>target</literal> parameter is a
<value>Buffer</value> or <value>Uint8Array</value> to copy into.

<para>
The <literal>targetStart</literal> is an integer specifying
the offset within target at which to begin writing,
by default is 0.
The <literal>sourceStart</literal> is an integer specifying
the offset within buffer from which to begin copying,
by default is 0.
The <literal>sourceEnd</literal> is an integer specifying
the offset within buffer at which to stop copying (not inclusive)
by default is <value>buf.length</value>.
</para>
</tag-desc>

<tag-name id="buf_equals"><literal>buf.equals(<value>otherBuffer</value>)</literal></tag-name>
<tag-desc>
A boolean value,
returns <literal>true</literal> if both Buffer and <value>otherBuffer</value>
have exactly the same bytes.
</tag-desc>

<tag-name id="buf_fill"><literal>buf.fill(<value>value</value>[,
<value>offset</value>[,
<value>end</value>]][,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
Fills the Buffer with the specified <value>value</value>.
If the <value>offset</value> and <value>end</value> are not specified,
the entire Buffer will be filled.
The <value>value</value> is coerced to <value>uint32</value> if it is not a
<literal>string</literal>,
<literal>Buffer</literal>, or
<literal>integer</literal>.
If the resulting integer is greater than 255,
the Buffer will be filled with <value>value</value> and 255.
</tag-desc>

<tag-name id="buf_includes"><literal>buf.includes(<value>value</value>[,
<value>byteOffset</value>][,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
Equivalent to
<link id="buf_indexof"><literal>buf.indexOf()</literal></link>
<literal>!== -1</literal>,
returns <literal>true</literal> if the <value>value</value> was found
in Buffer.
</tag-desc>

<tag-name id="buf_indexof"><literal>buf.indexOf(<value>value</value>[,
<value>byteOffset</value>][,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
Returns an integer which is the index of the first occurrence of
<value>value</value> in Buffer, or <value>-1</value>
if Buffer does not contain value.
The <value>value</value> can be a
<literal>string</literal> with specified <value>encoding</value>
(by default <value>utf8</value>),
<literal>Buffer</literal>,
<literal>Unit8Array</literal>,
or a number between 0 and 255.
</tag-desc>

<tag-name id="buf_lastindexof"><literal>buf.lastIndexOf(<value>value</value>[,
<value>byteOffset</value>][,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
The same as
<link id="buf_indexof"><literal>buf.indexOf()</literal></link>,
except the last occurrence of the <value>value</value> is found
instead of the first occurrence.
The <value>value</value> can be a string, Buffer, or
integer between 1 and 255.
If the <value>value</value> is an empty string or empty Buffer,
<literal>byteOffset</literal> will be returned.
</tag-desc>

<tag-name id="buf_length"><literal>buf.length</literal></tag-name>
<tag-desc>
Returns the number of bytes in Buffer.
</tag-desc>

<tag-name id="buf_readintbe"><literal>buf.readIntBE(<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Reads the <value>byteLength</value> from <literal>buf</literal>
at the specified <value>offset</value>
and interprets the result as a big-endian,
two's complement signed value supporting up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The similar methods are also supported:
<literal>buf.readInt8([offset])</literal>,
<literal>buf.readInt16BE([offset])</literal>,
<literal>buf.readInt32BE([offset])</literal>.
</para>
</tag-desc>

<tag-name id="buf_readintle"><literal>buf.readIntLE(<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Reads the <value>byteLength</value> from <literal>buf</literal>
at the specified <value>offset</value>
and interprets the result as a little-endian,
two's complement signed value supporting up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The similar methods are also supported:
<literal>buf.readInt8([offset])</literal>,
<literal>buf.readInt16LE([offset])</literal>,
<literal>buf.readInt32LE([offset])</literal>.
</para>
</tag-desc>

<tag-name id="buf_readuintbe"><literal>buf.readUIntBE(<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Reads the <value>byteLength</value> from <literal>buf</literal>
at the specified <value>offset</value>
and interprets the result as a big-endian
integer supporting up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The similar methods are also supported:
<literal>buf.readUInt8([offset])</literal>,
<literal>buf.readUInt16BE([offset])</literal>,
<literal>buf.readUInt32BE([offset])</literal>.
</para>
</tag-desc>

<tag-name id="buf_readuintle"><literal>buf.readUIntLE(<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Reads the <value>byteLength</value> from <literal>buf</literal>
at the specified <value>offset</value>
and interprets the result as a little-endian
integer supporting up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The similar methods are also supported:
<literal>buf.readUInt8([offset])</literal>,
<literal>buf.readUInt16LE([offset])</literal>,
<literal>buf.readUInt32LE([offset])</literal>.
</para>
</tag-desc>

<tag-name id="buf_readdobulebe"><literal>buf.readDoubleBE</literal>([<value>offset</value>])</tag-name>
<tag-desc>
Reads a 64-bit, big-endian double from <literal>buf</literal>
at the specified <value>offset</value>.
</tag-desc>

<tag-name id="buf_readdobulele"><literal>buf.readDoubleLE</literal>([<value>offset</value>])</tag-name>
<tag-desc>
Reads a 64-bit, little-endian double from <literal>buf</literal>
at the specified <value>offset</value>.
</tag-desc>

<tag-name id="buf_readfloatbe"><literal>buf.readFloatBE</literal>([<value>offset</value>])</tag-name>
<tag-desc>
Reads a 32-bit, big-endian float from <literal>buf</literal>
at the specified <value>offset</value>.
</tag-desc>

<tag-name id="buf_readfloatle"><literal>buf.readFloatLE</literal>([<value>offset</value>])</tag-name>
<tag-desc>
Reads a 32-bit, little-endian float from <literal>buf</literal>
at the specified <value>offset</value>.
</tag-desc>

<tag-name id="buf_subarray"><literal>buf.subarray[<value>start</value>[,
<value>end</value>]])</literal></tag-name>
<tag-desc>
Returns a new <literal>buf</literal>
that references the same memory as the original,
but offset and cropped by
<value>start</value> and <value>end</value>.
If <value>end</value> is greater than
<link id="buf_length"><literal>buf.length</literal></link>,
the same result as that of end equal to
<link id="buf_length"><literal>buf.length</literal></link>
is returned.
</tag-desc>

<tag-name id="buf_slice"><literal>buf.slice[<value>start</value>[,
<value>end</value>]])</literal></tag-name>
<tag-desc>
Returns a new <literal>buf</literal>
that references the same memory as the original,
but offset and cropped by the
<value>start</value> and <value>end</value> values.
The method is not compatible with the
<literal>Uint8Array.prototype.slice()</literal>,
which is a superclass of Buffer.
To copy the slice, use
<literal>Uint8Array.prototype.slice()</literal>.
</tag-desc>

<tag-name id="buf_swap16"><literal>buf.swap16</literal>()</tag-name>
<tag-desc>
Interprets <literal>buf</literal> as an array of unsigned 16-bit numbers
and swaps the byte order in-place.
Throws an error if
<link id="buf_length"><literal>buf.length</literal></link>
is not a multiple of 2.
</tag-desc>

<tag-name id="buf_swap32"><literal>buf.swap32</literal>()</tag-name>
<tag-desc>
Interprets <literal>buf</literal> as an array of unsigned 32-bit numbers
and swaps the byte order in-place.
Throws an error if
<link id="buf_length"><literal>buf.length</literal></link>
is not a multiple of 4.
</tag-desc>

<tag-name id="buf_swap64"><literal>buf.swap64</literal>()</tag-name>
<tag-desc>
Interprets <literal>buf</literal> as an array of 64-bit numbers
and swaps byte order in-place.
Throws an error if
<link id="buf_length"><literal>buf.length</literal></link>
is not a multiple of 8.
</tag-desc>

<tag-name id="buf_tojson"><literal>buf.toJSON</literal>()</tag-name>
<tag-desc>
Returns a JSON representation of <literal>buf.</literal>
<literal>JSON.stringify()</literal>
implicitly calls this function when stringifying a Buffer instance.
</tag-desc>

<tag-name id="buf_tostring"><literal>buf.toString([<value>encoding</value>[,
<value>start</value>[,
<value>end</value>]]])</literal></tag-name>
<tag-desc>
Decodes <literal>buf</literal> to a string
according to the specified character <value>encoding</value>
which can be <value>utf8</value>,
<value>hex</value>,
<value>base64</value>,
<value>base64url</value>.
The <value>start</value> and <value>end</value> parameters
may be passed to decode only a subset of Buffer.
</tag-desc>

<tag-name id="buf_write"><literal>buf.write(<value>string</value>[,
<value>offset</value>[,
<value>length</value>]][,
<value>encoding</value>])</literal></tag-name>
<tag-desc>
Writes a <value>string</value> to <literal>buf</literal>
at <value>offset</value>
according to the character <value>encoding</value>.
The <value>length</value> parameter is the number of bytes to write.
If Buffer did not contain enough space to fit the entire string,
only part of string will be written,
however, partially encoded characters will not be written.
The <value>encoding</value> can be
<value>utf8</value>,
<value>hex</value>,
<value>base64</value>,
<value>base64url</value>.
</tag-desc>

<tag-name id="buf_writeintbe"><literal>buf.writeIntBE(<value>value</value>,
<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Writes <value>byteLength</value> bytes of <value>value</value>
to <literal>buf</literal>
at the specified <value>offset</value> as big-endian.
Supports up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The following similar methods are also supported:
<literal>buf.writeInt8</literal>,
<literal>buf.writeInt16BE</literal>,
<literal>buf.writeInt32BE</literal>.
</para>
</tag-desc>

<tag-name id="buf_writeintle"><literal>buf.writeIntLE(<value>value</value>,
<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Writes <value>byteLength</value> bytes of <value>value</value>
to <literal>buf</literal>
at the specified <value>offset</value> as little-endian.
Supports up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The following similar methods are also supported:
<literal>buf.writeInt8</literal>,
<literal>buf.writeInt16LE</literal>,
<literal>buf.writeInt32LE</literal>.
</para>
</tag-desc>

<tag-name id="buf_writeuintbe"><literal>buf.writeUIntBE(<value>value</value>,
<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Writes <value>byteLength</value> bytes of <value>value</value>
to <literal>buf</literal>
at the specified <value>offset</value> as big-endian.
Supports up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The following similar methods are also supported:
<literal>buf.writeUInt8</literal>,
<literal>buf.writeUInt16BE</literal>,
<literal>buf.writeUInt32BE</literal>.
</para>
</tag-desc>

<tag-name id="buf_writeuintle"><literal>buf.writeUIntLE(<value>value</value>,
<value>offset</value>,
<value>byteLength</value>)</literal></tag-name>
<tag-desc>
Writes <value>byteLength</value> bytes of <value>value</value>
to <literal>buf</literal>
at the specified <value>offset</value> as little-endian.
Supports up to 48 bits of accuracy.
The <value>byteLength</value> parameter is an integer between 1 and 6
specifying the number of bytes to read.
<para>
The following similar methods are also supported:
<literal>buf.writeUInt8</literal>,
<literal>buf.writeUInt16LE</literal>,
<literal>buf.writeUInt32LE</literal>.
</para>
</tag-desc>

<tag-name id="buf_writedoublebe"><literal>buf.writeDoubleBE(<value>value</value>,
[<value>offset</value>])</literal></tag-name>
<tag-desc>
Writes the <value>value</value> to <literal>buf</literal>
at the specified <value>offset</value> as big-endian.
</tag-desc>

<tag-name id="buf_writedoublele"><literal>buf.writeDoubleLE(<value>value</value>,
[<value>offset</value>])</literal></tag-name>
<tag-desc>
Writes the <value>value</value> to <literal>buf</literal>
at the specified <value>offset</value> as little-endian.
</tag-desc>

<tag-name id="buf_writefloatbe"><literal>buf.writeFloatBE(<value>value</value>,
[<value>offset</value>])</literal></tag-name>
<tag-desc>
Writes the <value>value</value> to <literal>buf</literal>
at the specified <value>offset</value> as big-endian.
</tag-desc>

<tag-name id="buf_writefloatle"><literal>buf.writeFloatLE(<value>value</value>,
[<value>offset</value>])</literal></tag-name>
<tag-desc>
Writes the <value>value</value> to <literal>buf</literal>
at the specified <value>offset</value> as little-endian.
</tag-desc>

</list>
</para>

</section>


<section id="crypto" name="Crypto">

<para>
The Crypto module provides cryptographic functionality support.
The Crypto module object is returned by <literal>require('crypto')</literal>.
</para>

<para>
<list type="tag">

<tag-name id="crypto_createhash"><literal>crypto.createHash(<value>algorithm</value>)</literal></tag-name>
<tag-desc>
Creates and returns a <link id="crypto_hash">Hash</link> object
that can be used to generate hash digests
using the given <value>algorithm</value>.
The algorithm can be
<literal>md5</literal>,
<literal>sha1</literal>, and
<literal>sha256</literal>.
</tag-desc>

<tag-name id="crypto_createhmac"><literal>crypto.createHmac(<value>algorithm</value>,
<value>secret key</value>)</literal></tag-name>
<tag-desc>
Creates and returns an <link id="crypto_hmac">HMAC</link> object that uses
the given <value>algorithm</value> and <value>secret key</value>.
The algorithm can be
<literal>md5</literal>,
<literal>sha1</literal>, and
<literal>sha256</literal>.
</tag-desc>

</list>
</para>


<section id="crypto_hash" name="Hash">

<para>
<list type="tag">

<tag-name id="crypto_hash_update"><literal>hash.update(<value>data</value>)</literal></tag-name>
<tag-desc>
Updates the hash content with the given <value>data</value>.
</tag-desc>

<tag-name id="crypto_hash_digest"><literal>hash.digest([<value>encoding</value>])</literal></tag-name>
<tag-desc>
Calculates the digest of all of the data passed using
<literal>hash.update()</literal>.
The encoding can be
<literal>hex</literal>,
<literal>base64</literal>, and
<literal>base64url</literal>.
If encoding is not provided, a Buffer object
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>) is returned.
<note>
Before version (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
a byte string was returned instead of a Buffer object.
</note>
</tag-desc>

</list>
</para>

<para>
<example>
>> var cr = require('crypto')
undefined

>> cr.createHash('sha1').update('A').update('B').digest('base64url')
'BtlFlCqiamG-GMPiK_GbvKjdK10'
</example>
</para>

</section>


<section id="crypto_hmac" name="HMAC">

<para>
<list type="tag">

<tag-name id="crypto_hmac_update"><literal>hmac.update(<value>data</value>)</literal></tag-name>
<tag-desc>
Updates the HMAC content with the given <value>data</value>.
</tag-desc>

<tag-name id="crypto_hmac_digest"><literal>hmac.digest([<value>encoding</value>])</literal></tag-name>
<tag-desc>
Calculates the HMAC digest of all of the data passed using
<literal>hmac.update()</literal>.
The encoding can be
<literal>hex</literal>,
<literal>base64</literal>, and
<literal>base64url</literal>.
If encoding is not provided, a Buffer object
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>) is returned.
<note>
Before version <link doc="changes.xml" id="njs0.4.4">0.4.4</link>,
a byte string was returned instead of a Buffer object.
</note>
</tag-desc>
</list>
</para>

<para>
<example>
>> var cr = require('crypto')
undefined

>> cr.createHmac('sha1', 'secret.key').update('AB').digest('base64url')
'Oglm93xn23_MkiaEq_e9u8zk374'
</example>
</para>

</section>

</section>


<section id="njs_api_fs" name="File System">

<para>
The File System module provides operations with files.
</para>

<para>
The module object is returned by <literal>require('fs')</literal>.
Since <link doc="changes.xml" id="njs0.3.9">0.3.9</link>,
promissified versions of file system methods are available through
<literal>require('fs').promises</literal> object:
<example>
> var fs = require('fs').promises;
undefined
> fs.readFile("/file/path").then((data)=>console.log(data))
&lt;file data&gt;
</example>
<list type="tag">

<tag-name id="fs_accesssync"><literal>accessSync(<value>path</value>[,
<value>mode</value>])</literal></tag-name>
<tag-desc>
Synchronously tests permissions for a file or directory
specified in the <literal>path</literal>
(<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
If the check fails, an error will be returned,
otherwise, the method will return undefined.
<list type="tag">

<tag-name><literal>mode</literal></tag-name>
<tag-desc>
by default is <link id="access_const"><literal>fs.constants.F_OK</literal></link>.
The mode argument is an optional integer
that specifies the accessibility checks to be performed.
<example>
try {
    fs.accessSync('/file/path', fs.constants.R_OK | fs.constants.W_OK);
    console.log('has access');
} catch (e) {
    console.log('no access');)
}
</example>
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_appendfilesync"><literal>appendFileSync(<value>filename</value>,
<value>data</value>[, <value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously appends specified <literal>data</literal>
to a file with provided <literal>filename</literal>.
The <literal>data</literal> is expected to be a string
or a Buffer object (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
If the file does not exist, it will be created.
The <literal>options</literal> parameter is expected to be
an object with the following keys:
<list type="tag">

<tag-name><literal>mode</literal></tag-name>
<tag-desc>
mode option, by default is <literal>0o666</literal>
</tag-desc>

<tag-name><literal>flag</literal></tag-name>
<tag-desc>
file system <link id="njs_api_fs_flags">flag</link>,
by default is <literal>a</literal>
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_mkdirsync"><literal>mkdirSync(<value>path</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously creates a directory at the specified <literal>path</literal>
(<link doc="changes.xml" id="njs0.4.2">0.4.2</link>).
The <literal>options</literal> parameter is expected to be an
<literal>integer</literal> that specifies
the <link id="fs_mkdirsync_mode">mode</link>,
or an object with the following keys:
<list type="tag">

<tag-name id="fs_mkdirsync_mode"><literal>mode</literal></tag-name>
<tag-desc>
mode option, by default is <literal>0o777</literal>.
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_readdirsync"><literal>readdirSync(<value>path</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously reads the contents of a directory
at the specified <literal>path</literal>
(<link doc="changes.xml" id="njs0.4.2">0.4.2</link>).
The <literal>options</literal> parameter is expected to be
a string that specifies <link id="fs_readdirsync_encoding">encoding</link>
or an object with the following keys:
<list type="tag">

<tag-name id="fs_readdirsync_encoding"><literal>encoding</literal></tag-name>
<tag-desc>
encoding, by default is <literal>utf8</literal>.
The encoding can be <literal>utf8</literal> and <literal>buffer</literal>
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
</tag-desc>

<tag-name id="fs_readdirsync_withfiletypes"><literal>withFileTypes</literal></tag-name>
<tag-desc>
if set to <literal>true</literal>, the files array will contain
<link id="fs_dirent"><literal>fs.Dirent</literal></link> objects,
by default is <literal>false</literal>.
</tag-desc>

</list>
</tag-desc>

<tag-name id="fs_readfilesync"><literal>readFileSync(<value>filename</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously returns the contents of the file
with provided <literal>filename</literal>.
The <literal>options</literal> parameter holds
<literal>string</literal> that specifies encoding.
If an encoding is specified, a string is returned,
otherwise, a Buffer object
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>) is returned.
<note>
Before version <link doc="changes.xml" id="njs0.4.4">0.4.4</link>,
a <link id="string_tobytes">byte string</link> was returned
if encoding was not specified.
</note>
Otherwise, <literal>options</literal> is expected to be
an object with the following keys:
<list type="tag">

<tag-name><literal>encoding</literal></tag-name>
<tag-desc>
encoding, by default is not specified.
The encoding can be <literal>utf8</literal>,
<literal>hex</literal>
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
<literal>base64</literal>
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
<literal>base64url</literal>
(<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
</tag-desc>

<tag-name><literal>flag</literal></tag-name>
<tag-desc>
file system <link id="njs_api_fs_flags">flag</link>,
by default is <literal>r</literal>
</tag-desc>

</list>
<example>
>> var fs = require('fs')
undefined
>> var file = fs.readFileSync('/file/path.tar.gz')
undefined
>> var gzipped = file.slice(0,2).toString('hex') === '1f8b'; gzipped
true
</example>
</tag-desc>

<tag-name id="fs_realpathsync"><literal>realpathSync(<value>path</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously computes the canonical pathname by resolving
<literal>.</literal>, <literal>..</literal> and symbolic links using
<link url="http://man7.org/linux/man-pages/man3/realpath.3.html">realpath(3)</link>.
The <literal>options</literal> argument can be a string specifying an encoding,
or an object with an encoding property specifying the character encoding
to use for the path passed to the callback
(<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
</tag-desc>

<tag-name id="fs_renamesync"><literal>renameSync(<value>oldPath</value>,
<value>newPath</value>)</literal></tag-name>
<tag-desc>
Synchronously changes the name or location of a file from
<literal>oldPath</literal> to <literal>newPath</literal>
(<link doc="changes.xml" id="njs0.3.4">0.3.4</link>).
<example>
>> var fs = require('fs')
undefined
>> var file = fs.renameSync('hello.txt', 'HelloWorld.txt')
undefined
</example>
</tag-desc>

<tag-name id="fs_rmdirsync"><literal>rmdirSync(<value>path</value>)</literal></tag-name>
<tag-desc>
Synchronously removes a directory at the specified <literal>path</literal>
(<link doc="changes.xml" id="njs0.4.2">0.4.2</link>).
</tag-desc>

<tag-name id="fs_symlinksync"><literal>symlinkSync(<value>target</value>,
<value>path</value>)</literal></tag-name>
<tag-desc>
Synchronously creates the link called <literal>path</literal>
pointing to <literal>target</literal> using
<link url="http://man7.org/linux/man-pages/man2/symlink.2.html">symlink(2)</link>
(<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
Relative targets are relative to the link’s parent directory.
</tag-desc>

<tag-name id="fs_unlinksync"><literal>unlinkSync(<value>path</value>)</literal></tag-name>
<tag-desc>
Synchronously unlinks a file by <literal>path</literal>
(<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
</tag-desc>

<tag-name id="fs_writefilesync"><literal>writeFileSync(<value>filename</value>,
<value>data</value>[,
<value>options</value>])</literal></tag-name>
<tag-desc>
Synchronously writes <literal>data</literal> to a file
with provided <literal>filename</literal>.
The <literal>data</literal> is expected to be a string
or a Buffer object (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
If the file does not exist, it will be created,
if the file exists, it will be replaced.
The <literal>options</literal> parameter is expected to be
an object with the following keys:
<list type="tag">
<tag-name><literal>mode</literal></tag-name>
<tag-desc>
mode option, by default is <literal>0o666</literal>
</tag-desc>

<tag-name><literal>flag</literal></tag-name>
<tag-desc>
file system <link id="njs_api_fs_flags">flag</link>,
by default is <literal>w</literal>
</tag-desc>

</list>
<example>
>> var fs = require('fs')
undefined
>> var file = fs.writeFileSync('hello.txt', 'Hello world')
undefined
</example>
</tag-desc>

</list>
</para>


<section id="fs_dirent" name="fs.Dirent">

<para>
<literal>fs.Dirent</literal> is a representation of a directory entry&mdash;
a file or a subdirectory.
When
<link id="fs_readdirsync"><literal>readdirSync()</literal></link>
is called with the
<link id="fs_readdirsync_withfiletypes"><literal>withFileTypes</literal></link>
option,
the resulting array contains <literal>fs.Dirent</literal> objects.

<list type= "bullet" compact="no">

<listitem>
<literal>dirent.isBlockDevice()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a block device.
</listitem>

<listitem>
<literal>dirent.isCharacterDevice()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a character device.
</listitem>

<listitem>
<literal>dirent.isDirectory()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a file system directory.
</listitem>

<listitem>
<literal>dirent.isFIFO()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a first-in-first-out (FIFO) pipe.
</listitem>

<listitem>
<literal>dirent.isFile()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a regular file.
</listitem>

<listitem>
<literal>dirent.isSocket()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a socket.
</listitem>

<listitem>
<literal>dirent.isSymbolicLink()</literal>&mdash;returns
<literal>true</literal> if the <literal>fs.Dirent</literal> object describes
a symbolic link.
</listitem>

<listitem>
<literal>dirent.name</literal>&mdash;
the name of the file <literal>fs.Dirent</literal> object refers to.
</listitem>

</list>
</para>

</section>


<section id="access_const" name="File Access Constants">

<para>
The <link id="fs_accesssync"><literal>access()</literal></link> method
can accept the following flags.
These flags are exported by <literal>fs.constants</literal>:

<list type= "bullet" compact="no">

<listitem>
<literal>F_OK</literal>&mdash;indicates that the file
is visible to the calling process,
used by default if no mode is specified
</listitem>

<listitem>
<literal>R_OK</literal>&mdash;indicates that the file can be
read by the calling process
</listitem>

<listitem>
<literal>W_OK</literal>&mdash;indicates that the file can be
written by the calling process
</listitem>

<listitem>
<literal>X_OK</literal>&mdash;indicates that the file can be
executed by the calling process
</listitem>

</list>
</para>

</section>


<section id="njs_api_fs_flags" name="File System Flags">

<para>
The <literal>flag</literal> option can accept the following values:

<list type= "bullet" compact="no">

<listitem>
<literal>a</literal>&mdash;open a file for appending.
The file is created if it does not exist
</listitem>

<listitem>
<literal>ax</literal>&mdash;the same as <literal>a</literal>
but fails if the file already exists
</listitem>

<listitem>
<literal>a+</literal>&mdash;open a file for reading and appending.
If the file does not exist, it will be created
</listitem>

<listitem>
<literal>ax+</literal>&mdash;the same as <literal>a+</literal>
but fails if the file already exists
</listitem>

<listitem>
<literal>as</literal>&mdash;open a file for appending
in synchronous mode.
If the file does not exist, it will be created
</listitem>

<listitem>
<literal>as+</literal>&mdash;open a file for reading and appending
in synchronous mode.
If the file does not exist, it will be created
</listitem>

<listitem>
<literal>r</literal>&mdash;open a file for reading.
An exception occurs if the file does not exist
</listitem>

<listitem>
<literal>r+</literal>&mdash;open a file for reading and writing.
An exception occurs if the file does not exist
</listitem>

<listitem>
<literal>rs+</literal>&mdash;open a file for reading and writing
in synchronous mode.
Instructs the operating system to bypass the local file system cache
</listitem>

<listitem>
<literal>w</literal>&mdash;open a file for writing.
If the file does not exist, it will be created.
If the file exists, it will be replaced
</listitem>

<listitem>
<literal>wx</literal>&mdash;the same as <literal>w</literal>
but fails if the file already exists
</listitem>

<listitem>
<literal>w+</literal>&mdash;open a file for reading and writing.
If the file does not exist, it will be created.
If the file exists, it will be replaced
</listitem>

<listitem>
<literal>wx+</literal>&mdash;the same as <literal>w+</literal>
but fails if the file already exists
</listitem>

</list>
</para>

</section>

</section>


<section id="querystring" name="Query String">

<para>
The Query String module provides support
for parsing and formatting URL query strings
(<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
The Query String module object is returned by
<literal>require('querystring')</literal>.
</para>

<para>
<list type="tag">

<tag-name id="querystring_decode"><literal>querystring.decode()</literal></tag-name>
<tag-desc>
is an alias for
<link id="querystring_parse"><literal>querystring.parse()</literal></link>.
</tag-desc>

<tag-name id="querystring_encode"><literal>querystring.encode()</literal></tag-name>
<tag-desc>
is an alias for
<link id="querystring_stringify"><literal>querystring.stringify()</literal></link>.
</tag-desc>

<tag-name id="querystring_escape"><literal>querystring.escape(<value>string</value>)</literal></tag-name>
<tag-desc>
<para>
Performs URL encoding of the given <literal>string</literal>,
returns an escaped query string.
The method is used by
<link id="querystring_stringify"><literal>querystring.stringify()</literal></link>
and should not be used directly.
</para>
</tag-desc>

<tag-name id="querystring_parse"><literal>querystring.parse(<value>string</value>[,
<value>separator</value>[,
<value>equal</value>[,
<value>options</value>]]])</literal></tag-name>
<tag-desc>
<para>
Parses the query string URL and returns an object.
</para>

<para>
The <literal>separator</literal> parameter is a substring
for delimiting key and value pairs in the query string,
by default is “<literal>&amp;</literal>”.
</para>

<para>
The <literal>equal</literal> parameter is a substring
for delimiting keys and values in the query string,
by default is “<literal>=</literal>”.
</para>

<para>
The <literal>options</literal> parameter is expected to be
an object with the following keys:
<list type="tag">
<tag-name><literal>decodeURIComponent</literal>
<value>function</value></tag-name>
<tag-desc>
Function used
to decode percent-encoded characters in the query string,
by default is
<link id="querystring_unescape"><literal>querystring.unescape()</literal></link>
</tag-desc>

<tag-name><literal>maxKeys</literal>
<value>number</value></tag-name>
<tag-desc>
the maximum number of keys to parse,
by default is <literal>1000</literal>.
The <literal>0</literal> value removes limitations for counting keys.
</tag-desc>

</list>
By default, percent-encoded characters within the query string are assumed
to use the UTF-8 encoding,
invalid UTF-8 sequences will be replaced with
the <literal>U+FFFD</literal> replacement character.
</para>

<para>
For example, for the following query string
<example>
'foo=bar&amp;abc=xyz&amp;abc=123'
</example>
the output will be:
<example>
{
  foo: 'bar',
  abc: ['xyz', '123']
}
</example>
</para>

</tag-desc>

<tag-name id="querystring_stringify"><literal>querystring.stringify(<value>object</value>[,
<value>separator</value>[,
<value>equal</value>[,
<value>options</value>]]])</literal></tag-name>
<tag-desc>
<para>
Serializes an object and returns a URL query string.
</para>

<para>
The <literal>separator</literal> parameter is a substring
for delimiting key and value pairs in the query string,
by default is “<literal>&amp;</literal>”.
</para>

<para>
The <literal>equal</literal> parameter is a substring
for delimiting keys and values in the query string,
by default is “<literal>=</literal>”.
</para>

<para>
The <literal>options</literal> parameter is expected to be
an object with the following keys:
<list type="tag">
<tag-name><literal>encodeURIComponent</literal>
<value>function</value></tag-name>
<tag-desc>
The function to use when converting
URL-unsafe characters to percent-encoding in the query string,
by default is
<link id="querystring_escape"><literal>querystring.escape()</literal></link>.
</tag-desc>

</list>
</para>

<para>
By default, characters that require percent-encoding within the query string
are encoded as UTF-8.
If other encoding is required, then
<literal>encodeURIComponent</literal> option should be specified.
</para>

<para>
For example, for the following command
<example>
querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], 123: '' });
</example>
the query string will be:
<example>
'foo=bar&amp;baz=qux&amp;baz=quux&amp;123='
</example>
</para>

</tag-desc>

<tag-name id="querystring_unescape"><literal>querystring.unescape(<value>string</value>)</literal></tag-name>
<tag-desc>
<para>
Performs decoding of URL percent-encoded characters
of the <literal>string</literal>,
returns an unescaped query string.
The method is used by
<link id="querystring_parse"><literal>querystring.parse()</literal></link>
and should not be used directly.
</para>
</tag-desc>

</list>
</para>

</section>

</section>

</article>