annotate xml/en/docs/njs/reference.xml @ 2848:c8d57f14c51b

Documented escaped URIs for r.internalRedirect in njs.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 17 May 2022 12:53:09 +0100
parents f5e49925e9db
children 1e1a15c84515
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2175
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
2
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
3 <!--
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
4 Copyright (C) Nginx, Inc.
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
5 -->
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
6
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
8
2246
32ba43abf9cd Renamed njs API, njs Changes.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2245
diff changeset
9 <article name="Reference"
32ba43abf9cd Renamed njs API, njs Changes.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2245
diff changeset
10 link="/en/docs/njs/reference.html"
2175
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
11 lang="en"
2848
c8d57f14c51b Documented escaped URIs for r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2847
diff changeset
12 rev="82">
2175
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
13
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
14 <section id="summary">
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
15
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
16 <para>
2244
467aef18bf12 Renamed the "About njs" page.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2237
diff changeset
17 <link doc="index.xml">njs</link> provides objects, methods and properties
2175
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
18 for extending nginx functionality.
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
19 </para>
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
20
2569
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
21 <para>
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
22 This reference contains only njs specific properties, methods and modules
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
23 not compliant with ECMAScript.
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
24 Definitions of njs properties and methods compliant with ECMAScript
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
25 can be found in
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
26 <link url="http://www.ecma-international.org/ecma-262/">ECMAScript
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
27 specification</link>.
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
28 List of all njs properties and methods can be found in
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
29 <link doc="compatibility.xml">Compatibility</link>.
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
30 </para>
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
31
2175
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
32 </section>
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
33
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
34
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
35 <section id="http_stream" name="nginx objects">
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
36
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
37
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
38 <section id="http" name="HTTP Request">
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
39
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
40 <para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
41 The HTTP request object is available only in the
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
42 <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> module.
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
43 All string properties of the object are
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
44 <link id="string">byte strings</link>.
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
45
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
46 <list type="tag">
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
47
2353
21f3a93fbe97 njs-0.3.0
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2348
diff changeset
48 <tag-name id="r_args"><literal>r.args{}</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
49 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
50 request arguments object, read-only
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
51 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
52
2663
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
53 <tag-name id="r_done"><literal>r.done()</literal></tag-name>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
54 <tag-desc>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
55 after calling this function,
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
56 next data chunks will be passed to client without calling
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
57 <link doc="../http/ngx_http_js_module.xml" id="js_body_filter"/>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
58 (<link doc="changes.xml" id="njs0.5.2">0.5.2</link>).
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
59 May be called only from the
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
60 <link doc="../http/ngx_http_js_module.xml" id="js_body_filter"/> function
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
61 </tag-desc>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
62
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
63 <tag-name id="r_error"><literal>r.error(<value>string</value>)</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
64 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
65 writes a <literal>string</literal> to the error log
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
66 on the <literal>error</literal> level of logging
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
67 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
68
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
69 <tag-name id="r_finish"><literal>r.finish()</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
70 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
71 finishes sending a response to the client
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
72 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
73
2353
21f3a93fbe97 njs-0.3.0
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2348
diff changeset
74 <tag-name id="r_headers_in"><literal>r.headersIn{}</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
75 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
76 incoming headers object, read-only.
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
77 <para>
2543
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
78 The <literal>Foo</literal> request header
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
79 can be accessed with the syntax:
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
80 <literal>headersIn.foo</literal> or <literal>headersIn['Foo']</literal>.
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
81 </para>
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
82
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
83 <para>
2735
ff357b676c2e Removed trailing spaces.
Maxim Dounin <mdounin@mdounin.ru>
parents: 2716
diff changeset
84 The
2543
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
85 <header>Authorization</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
86 <header>Content-Length</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
87 <header>Content-Range</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
88 <header>Content-Type</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
89 <header>ETag</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
90 <header>Expect</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
91 <header>From</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
92 <header>Host</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
93 <header>If-Match</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
94 <header>If-Modified-Since</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
95 <header>If-None-Match</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
96 <header>If-Range</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
97 <header>If-Unmodified-Since</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
98 <header>Max-Forwards</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
99 <header>Proxy-Authorization</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
100 <header>Referer</header>,
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
101 <header>Transfer-Encoding</header>, and
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
102 <header>User-Agent</header>
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
103 request headers can have only one field value
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
104 (<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
105 Duplicate field values in <header>Cookie</header> headers
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
106 are separated by semicolon (<literal>;</literal>).
f39c4724c0f8 Described multi-value headers in r.headersIn.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2537
diff changeset
107 Duplicate field values in all other request headers are separated by commas.
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
108 </para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
109 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
110
2331
5eba0f7b24a9 njs-0.2.8
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2315
diff changeset
111 <tag-name id="r_headers_out"><literal>r.headersOut{}</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
112 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
113 outgoing headers object, writable.
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
114 <para>
2532
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
115 The <header>Foo</header> response header
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
116 can be accessed with the syntax:
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
117 <literal>headersOut.foo</literal> or <literal>headersOut['Foo']</literal>.
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
118 </para>
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
119
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
120 <para>
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
121 Field values of multi-value response headers
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
122 (<link doc="changes.xml" id="njs0.4.0">0.4.0</link>)
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
123 can be set with the syntax:
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
124 <example>
2544
33347df1da9c Relocated sentence in r.headers.Out, added dot, corrected quotes.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2543
diff changeset
125 r.headersOut['Foo'] = ['a', 'b']
2532
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
126 </example>
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
127 where the output will be:
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
128 <example>
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
129 Foo: a
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
130 Foo: b
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
131 </example>
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
132 All previous field values of the <header>Foo</header> response header
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
133 will be deleted.
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
134 </para>
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
135
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
136 <para>
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
137 For standard response headers
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
138 that accept only a single field value such as
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
139 <header>Content-Type</header>,
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
140 only the last element of the array will take effect.
2544
33347df1da9c Relocated sentence in r.headers.Out, added dot, corrected quotes.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2543
diff changeset
141 Field values of the <header>Set-Cookie</header> response header
33347df1da9c Relocated sentence in r.headers.Out, added dot, corrected quotes.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2543
diff changeset
142 are always returned as an array.
2532
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
143 Duplicate field values in
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
144 <header>Age</header>,
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
145 <header>Content-Encoding</header>,
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
146 <header>Content-Length</header>,
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
147 <header>Content-Type</header>,
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
148 <header>ETag</header>,
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
149 <header>Expires</header>,
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
150 <header>Last-Modified</header>,
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
151 <header>Location</header>,
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
152 <header>Retry-After</header>
423d813dc8bb Documented support for multi-value headers in r.headersOut.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2525
diff changeset
153 response headers are ignored.
2537
d6bbfd20c82f Rephrased a sentence in r.headersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2532
diff changeset
154 Duplicate field values in all other response headers
d6bbfd20c82f Rephrased a sentence in r.headersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2532
diff changeset
155 are separated by commas.
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
156 </para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
157 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
158
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
159 <tag-name id="r_http_version"><literal>r.httpVersion</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
160 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
161 HTTP version, read-only
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
162 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
163
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
164 <tag-name id="r_internal_redirect"><literal>r.internalRedirect(<value>uri</value>)</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
165 <tag-desc>
2685
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
166 performs an
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
167 <link doc="../dev/development_guide.xml" id="http_request_redirection">internal
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
168 redirect</link>
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
169 to the specified <literal>uri</literal>.
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
170 If the uri starts with the “<literal>@</literal>” prefix,
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
171 it is considered a named location.
2685
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
172 Redirected requests become internal and can access the
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
173 <link doc="../http/ngx_http_core_module.xml" id="internal">internal</link>
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
174 locations.
2525
6ce28e0beec0 Updated description of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2509
diff changeset
175 The actual redirect happens after the handler execution is completed.
2685
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
176 <para>
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
177 <note>
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
178 After redirect,
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
179 a new njs VM is started in the target location,
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
180 the VM in the original location is stopped.
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
181 Values of nginx variables are kept
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
182 and can be used to pass information to the target location.
2716
f82f16e327f2 Added info about js_var to r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2693
diff changeset
183 Since <link doc="changes.xml" id="njs0.5.3">0.5.3</link>,
f82f16e327f2 Added info about js_var to r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2693
diff changeset
184 the variable declared with the <literal>js_var</literal> directive for
f82f16e327f2 Added info about js_var to r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2693
diff changeset
185 <link doc="../http/ngx_http_js_module.xml" id="js_var">http</link> or
f82f16e327f2 Added info about js_var to r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2693
diff changeset
186 <link doc="../stream/ngx_stream_js_module.xml" id="js_var">stream</link>
f82f16e327f2 Added info about js_var to r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2693
diff changeset
187 can be used.
2685
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
188 </note>
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
189 </para>
5282d6d3d849 Improved descripion of r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2679
diff changeset
190
2848
c8d57f14c51b Documented escaped URIs for r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2847
diff changeset
191 <para>
c8d57f14c51b Documented escaped URIs for r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2847
diff changeset
192 <note>
c8d57f14c51b Documented escaped URIs for r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2847
diff changeset
193 Since <link doc="changes.xml" id="njs0.7.4">0.7.4</link>,
c8d57f14c51b Documented escaped URIs for r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2847
diff changeset
194 the method accepts escaped URIs.
c8d57f14c51b Documented escaped URIs for r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2847
diff changeset
195 </note>
c8d57f14c51b Documented escaped URIs for r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2847
diff changeset
196 </para>
c8d57f14c51b Documented escaped URIs for r.internalRedirect in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2847
diff changeset
197
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
198 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
199
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
200 <tag-name id="r_log"><literal>r.log(<value>string</value>)</literal></tag-name>
2545
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
201 <tag-desc>
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
202 writes a <literal>string</literal> to the error log
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
203 on the <literal>info</literal> level of logging
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
204 </tag-desc>
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
205
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
206 <tag-name id="r_method"><literal>r.method</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
207 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
208 HTTP method, read-only
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
209 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
210
2497
805c4b84cc61 Added missing feature and links to njs-0.3.8 Changes.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2496
diff changeset
211 <tag-name id="r_parent"><literal>r.parent</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
212 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
213 references the parent request object
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
214 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
215
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
216 <tag-name id="r_remote_address"><literal>r.remoteAddress</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
217 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
218 client address, read-only
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
219 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
220
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
221 <tag-name id="r_request_body"><literal>r.requestBody</literal></tag-name>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
222 <tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
223 the property is deprecated since
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
224 <link doc="changes.xml" id="njs0.5.0">0.5.0</link>,
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
225 the <link id="r_request_buffer"><literal>r.requestBuffer</literal></link> or
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
226 <link id="r_request_text"><literal>r.requestText</literal></link> property
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
227 should be used instead.
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
228 </tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
229
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
230 <tag-name id="r_request_buffer"><literal>r.requestBuffer</literal></tag-name>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
231 <tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
232 client request body if it has not been written to a temporary file
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
233 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
234 To ensure that the client request body is in memory,
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
235 its size should be limited by
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
236 <link doc="../http/ngx_http_core_module.xml" id="client_max_body_size"/>,
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
237 and a sufficient buffer size should be set using
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
238 <link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/>.
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
239 The property is available only in the
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
240 <link doc="../http/ngx_http_js_module.xml" id="js_content"/> directive.
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
241 </tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
242
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
243 <tag-name id="r_request_text"><literal>r.requestText</literal></tag-name>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
244 <tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
245 the same as <link id="r_request_buffer"><literal>r.requestBuffer</literal></link>,
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
246 but returns a <literal>string</literal>.
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
247 Note that
2688
dd2bbd104146 Unified spelling of UTF-8 in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2687
diff changeset
248 it may convert bytes invalid in UTF-8 encoding into the replacement character.
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
249 </tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
250
2546
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
251 <tag-name id="r_raw_headers_in"><literal>r.rawHeadersIn{}</literal></tag-name>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
252 <tag-desc>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
253 returns an array of key-value pairs
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
254 exactly as they were received from the client
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
255 (<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
256 <para>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
257 For example, with the following request headers:
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
258 <example>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
259 Host: localhost
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
260 Foo: bar
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
261 foo: bar2
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
262 </example>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
263 the output of <literal>r.rawHeadersIn</literal> will be:
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
264 <example>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
265 [
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
266 ['Host', 'localhost'],
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
267 ['Foo', 'bar'],
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
268 ['foo', 'bar2']
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
269 ]
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
270 </example>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
271 All <literal>foo</literal> headers
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
272 can be collected with the syntax:
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
273 <example>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
274 r.rawHeadersIn.filter(v=>v[0].toLowerCase() == 'foo').map(v=>v[1])
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
275 </example>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
276 the output will be:
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
277 <example>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
278 ['bar', 'bar2']
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
279 </example>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
280 Header field names are not converted to lower case,
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
281 duplicate field values are not merged.
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
282 </para>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
283 </tag-desc>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
284
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
285 <tag-name id="r_raw_headers_out"><literal>r.rawHeadersOut{}</literal></tag-name>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
286 <tag-desc>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
287 returns an array of key-value pairs of response headers
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
288 (<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
289 Header field names are not converted to lower case,
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
290 duplicate field values are not merged.
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
291 </tag-desc>
6093e9f3615e Documented rawHeadersIn and rawHeadersOut in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2545
diff changeset
292
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
293 <tag-name id="r_response_body"><literal>r.responseBody</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
294 <tag-desc>
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
295 the property is deprecated since
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
296 <link doc="changes.xml" id="njs0.5.0">0.5.0</link>,
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
297 the <link id="r_response_buffer"><literal>r.responseBuffer</literal></link>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
298 or
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
299 the <link id="r_response_text"><literal>r.responseText</literal></link>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
300 property
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
301 should be used instead.
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
302 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
303
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
304 <tag-name id="r_response_buffer"><literal>r.responseBuffer</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
305 <tag-desc>
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
306 holds the <link id="r_subrequest">subrequest</link> response body,
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
307 read-only
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
308 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
309 The size of <literal>r.responseBuffer</literal> is limited by the
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
310 <link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
311 directive.
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
312 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
313
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
314 <tag-name id="r_response_text"><literal>r.responseText</literal></tag-name>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
315 <tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
316 the same as <link id="r_response_buffer"><literal>r.responseBuffer</literal></link>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
317 but returns a string
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
318 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
319 Note that
2688
dd2bbd104146 Unified spelling of UTF-8 in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2687
diff changeset
320 it may convert bytes invalid in UTF-8 encoding into the replacement character.
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
321 </tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
322
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
323 <tag-name id="r_return"><literal>r.return(status[,
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
324 string | Buffer])</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
325 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
326 sends the entire response
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
327 with the specified <literal>status</literal> to the client.
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
328 The response can be a string or Buffer
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
329 (<link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
330 <para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
331 It is possible to specify either a redirect URL
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
332 (for codes 301, 302, 303, 307, and 308)
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
333 or the response body text (for other codes) as the second argument
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
334 </para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
335 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
336
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
337 <tag-name id="r_send"><literal>r.send(string
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
338 | Buffer)</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
339 <tag-desc>
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
340 sends a part of the response body to the client.
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
341 The data sent can be a string or Buffer
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
342 (<link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
343 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
344
2663
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
345 <tag-name id="r_sendbuffer"><literal>r.sendBuffer(<value>data</value>[,
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
346 <value>options</value>])</literal></tag-name>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
347 <tag-desc>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
348 adds data to the chain of data chunks to be forwarded to the next body filter
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
349 (<link doc="changes.xml" id="njs0.5.2">0.5.2</link>).
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
350 The actual forwarding happens later,
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
351 when the all the data chunks of the current chain are processed.
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
352 <para>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
353 The data can be a string or Buffer.
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
354 The <literal>options</literal> is an object used
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
355 to override nginx buffer flags derived from an incoming data chunk buffer.
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
356 The flags can be overridden with the following flags:
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
357 <list type="tag">
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
358
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
359 <tag-name><literal>last</literal></tag-name>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
360 <tag-desc>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
361 boolean,
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
362 true if the buffer is the last buffer
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
363 </tag-desc>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
364
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
365 <tag-name><literal>flush</literal></tag-name>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
366 <tag-desc>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
367 boolean,
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
368 true if the buffer should have the <literal>flush</literal> flag
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
369 </tag-desc>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
370 </list>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
371 </para>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
372 The method may be called only from the
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
373 <link doc="../http/ngx_http_js_module.xml" id="js_body_filter"/> function.
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
374 </tag-desc>
a33d8f0f48b2 Documented r.done and r.sendBuffer in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2653
diff changeset
375
2571
3e47eecce384 Added id to r.sendHeader in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2570
diff changeset
376 <tag-name id="r_send_header"><literal>r.sendHeader()</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
377 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
378 sends the HTTP headers to the client
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
379 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
380
2800
3a146e49f9d4 Corrected syntax of r.setReturnValue and s.setReturnValue.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2792
diff changeset
381 <tag-name id="r_set_return_value"><literal>r.setReturnValue(<value>value</value>)</literal></tag-name>
2777
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
382 <tag-desc>
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
383 sets the return value of the
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
384 <link doc="../http/ngx_http_js_module.xml" id="js_set"/> handler
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
385 (<link doc="changes.xml" id="njs0.7.0">0.7.0</link>).
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
386 Unlike an ordinary return statement,
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
387 this method should be used when the handler is JS async function.
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
388 For example:
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
389 <example>
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
390 async function js_set(r) {
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
391 const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
392 r.setReturnValue(digest);
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
393 }
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
394 </example>
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
395 </tag-desc>
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
396
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
397 <tag-name id="r_status"><literal>r.status</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
398 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
399 status, writable
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
400 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
401
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
402 <tag-name id="r_subrequest"><literal>r.subrequest(<value>uri</value>[,
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
403 <value>options</value>[, <value>callback</value>]])</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
404 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
405 creates a subrequest with the given <literal>uri</literal> and
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
406 <literal>options</literal>, and installs
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
407 an optional completion <literal>callback</literal>.
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
408
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
409 <para>
2340
537130c40c1f Updated r.subrequest desctiption in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2338
diff changeset
410 A
537130c40c1f Updated r.subrequest desctiption in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2338
diff changeset
411 <link doc="../dev/development_guide.xml.xml" id="http_subrequests">subrequest</link>
537130c40c1f Updated r.subrequest desctiption in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2338
diff changeset
412 shares its input headers with the client request.
537130c40c1f Updated r.subrequest desctiption in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2338
diff changeset
413 To send headers different from original headers to a proxied server, the
537130c40c1f Updated r.subrequest desctiption in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2338
diff changeset
414 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_set_header"/>
537130c40c1f Updated r.subrequest desctiption in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2338
diff changeset
415 directive can be used.
537130c40c1f Updated r.subrequest desctiption in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2338
diff changeset
416 To send a completely new set of headers to a proxied server, the
537130c40c1f Updated r.subrequest desctiption in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2338
diff changeset
417 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass_request_headers"/>
537130c40c1f Updated r.subrequest desctiption in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2338
diff changeset
418 directive can be used.
537130c40c1f Updated r.subrequest desctiption in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2338
diff changeset
419 </para>
537130c40c1f Updated r.subrequest desctiption in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2338
diff changeset
420
537130c40c1f Updated r.subrequest desctiption in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2338
diff changeset
421 <para>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
422 If <literal>options</literal> is a string, then it
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
423 holds the subrequest arguments string.
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
424 Otherwise, <literal>options</literal> is expected to be
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
425 an object with the following keys:
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
426 <list type="tag">
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
427 <tag-name><literal>args</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
428 <tag-desc>
2344
ea8ccaac18b4 Added default values for r.subrequest options in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2340
diff changeset
429 arguments string, by default an empty string is used
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
430 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
431 <tag-name><literal>body</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
432 <tag-desc>
2344
ea8ccaac18b4 Added default values for r.subrequest options in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2340
diff changeset
433 request body,
ea8ccaac18b4 Added default values for r.subrequest options in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2340
diff changeset
434 by default the request body of the parent request object is used
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
435 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
436
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
437 <tag-name><literal>method</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
438 <tag-desc>
2344
ea8ccaac18b4 Added default values for r.subrequest options in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2340
diff changeset
439 HTTP method, by default the <literal>GET</literal> method is used
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
440 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
441
2507
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
442 <tag-name><literal>detached</literal></tag-name>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
443 <tag-desc>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
444 boolean flag (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>),
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
445 if <literal>true</literal>, the created subrequest is a detached subrequest.
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
446 Responses to detached subrequests are ignored.
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
447 Unlike ordinary subrequests, a detached subrequest
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
448 can be created inside a variable handler.
2579
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
449 The <literal>detached</literal> flag and callback argument
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
450 are mutually exclusive.
2507
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
451 </tag-desc>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
452
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
453 </list>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
454 </para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
455
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
456 <para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
457 The completion <literal>callback</literal> receives
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
458 a subrequest response object with methods and properties
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
459 identical to the parent request object.
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
460 </para>
2484
2aa02672d54f Added a note to r.subrequest in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2446
diff changeset
461
2aa02672d54f Added a note to r.subrequest in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2446
diff changeset
462 <para>
2aa02672d54f Added a note to r.subrequest in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2446
diff changeset
463 Since <link doc="changes.xml" id="njs0.3.8">0.3.8</link>,
2aa02672d54f Added a note to r.subrequest in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2446
diff changeset
464 if a <literal>callback</literal> is not provided,
2aa02672d54f Added a note to r.subrequest in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2446
diff changeset
465 the <literal>Promise</literal> object
2aa02672d54f Added a note to r.subrequest in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2446
diff changeset
466 that resolves to the subrequest response object is returned.
2aa02672d54f Added a note to r.subrequest in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2446
diff changeset
467 </para>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
468 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
469
2545
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
470 <tag-name id="r_uri"><literal>r.uri</literal></tag-name>
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
471 <tag-desc>
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
472 current <link doc="../http/ngx_http_core_module.xml" id="var_uri">URI</link>
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
473 in request,
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
474 <link doc="../http/ngx_http_core_module.xml" id="location">normalized</link>,
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
475 read-only
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
476 </tag-desc>
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
477
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
478 <tag-name id="r_raw_variables"><literal>r.rawVariables{}</literal></tag-name>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
479 <tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
480 nginx <link id="r_variables">variables</link> as Buffers,
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
481 writable
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
482 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
483 </tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
484
2545
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
485 <tag-name id="r_variables"><literal>r.variables{}</literal></tag-name>
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
486 <tag-desc>
2579
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
487 nginx variables object, writable
2689
7e271437f12e Updated writable variables info in r.variables and s.variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2688
diff changeset
488 (since <link doc="changes.xml" id="njs0.2.8">0.2.8</link>).
2693
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
489
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
490 <para>
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
491 A variable is writable if:
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
492 <list type="bullet">
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
493
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
494 <listitem>
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
495 it was created using the <literal>js_var</literal> directive for
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
496 <link doc="../http/ngx_http_js_module.xml" id="js_var">http</link> or
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
497 <link doc="../stream/ngx_stream_js_module.xml" id="js_var">stream</link>
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
498 (since <link doc="changes.xml" id="njs0.5.3">0.5.3</link>)
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
499 </listitem>
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
500
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
501 <listitem>
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
502 it is referenced in nginx configuration file
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
503 </listitem>
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
504
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
505 </list>
2689
7e271437f12e Updated writable variables info in r.variables and s.variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2688
diff changeset
506 Even so, some embedded variables still cannot be assigned a value (for example,
7e271437f12e Updated writable variables info in r.variables and s.variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2688
diff changeset
507 <link doc="../http/ngx_http_core_module.xml" id="var_http_"><literal>$http_</literal></link>).
2693
3cbd6e440581 Documented the js_var directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2689
diff changeset
508 </para>
2545
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
509 </tag-desc>
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
510
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
511 <tag-name id="r_warn"><literal>r.warn(<value>string</value>)</literal></tag-name>
2545
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
512 <tag-desc>
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
513 writes a <literal>string</literal> to the error log
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
514 on the <literal>warning</literal> level of logging
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
515 </tag-desc>
dca5a7053a6c Sorted alphabetically njs http methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2544
diff changeset
516
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
517 </list>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
518 </para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
519
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
520 </section>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
521
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
522
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
523 <section id="stream" name="Stream Session">
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
524
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
525 <para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
526 The stream session object is available only in the
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
527 <link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
528 module.
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
529 All string properties of the object are <link id="string">byte strings</link>.
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
530 </para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
531
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
532 <para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
533 <list type="tag">
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
534
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
535 <tag-name id="s_allow"><literal>s.allow()</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
536 <tag-desc>
2670
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
537 an alias to
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
538 <link id="s_done"><literal>s.done(0)</literal></link>
2337
867fe207f13e Updated links to changes.xml in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2332
diff changeset
539 (<link doc="changes.xml" id="njs0.2.4">0.2.4</link>)
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
540 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
541
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
542 <tag-name id="s_decline"><literal>s.decline()</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
543 <tag-desc>
2670
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
544 an alias to
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
545 <link id="s_done"><literal>s.done(-5)</literal></link>
2337
867fe207f13e Updated links to changes.xml in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2332
diff changeset
546 (<link doc="changes.xml" id="njs0.2.4">0.2.4</link>)
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
547 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
548
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
549 <tag-name id="s_deny"><literal>s.deny()</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
550 <tag-desc>
2670
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
551 an alias to
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
552 <link id="s_done"><literal>s.done(403)</literal></link>
2337
867fe207f13e Updated links to changes.xml in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2332
diff changeset
553 (<link doc="changes.xml" id="njs0.2.4">0.2.4</link>)
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
554 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
555
2670
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
556 <tag-name id="s_done"><literal>s.done([<value>code</value>]</literal>)</tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
557 <tag-desc>
2670
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
558 sets an exit <literal>code</literal> for the current
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
559 <link doc="../stream/stream_processing.xml">phase</link> handler
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
560 to a code value, by default <literal>0</literal>.
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
561 The actual finalization happens when the js handler is completed
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
562 and all pending events, for example, from
2679
8f3e9ff2785f Corrected syntax of njs.on() and ngx.fetch() in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2670
diff changeset
563 <link id="ngx_fetch"><literal>ngx.fetch()</literal></link> or
2670
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
564 <link id="settimeout"><literal>setTimeout()</literal></link>,
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
565 are processed
2337
867fe207f13e Updated links to changes.xml in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2332
diff changeset
566 (<link doc="changes.xml" id="njs0.2.4">0.2.4</link>).
2670
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
567 <para>
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
568 Possible code values:
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
569 <list type="bullet">
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
570
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
571 <listitem>
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
572 <literal>0</literal>&mdash;
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
573 successful finalization, passing control to the next phase
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
574 </listitem>
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
575
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
576 <listitem>
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
577 <literal>-5</literal>&mdash;
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
578 undecided, passing control to the next handler of the current phase (if any)
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
579 </listitem>
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
580
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
581 <listitem>
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
582 <literal>403</literal>&mdash;
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
583 access is forbidden
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
584 </listitem>
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
585
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
586 </list>
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
587 </para>
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
588 May be called only from a phase handler function:
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
589 <link doc="../stream/ngx_stream_js_module.xml" id="js_access"><literal>js_access</literal></link>
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
590 or
e53592a1d979 Improved descriptions of s.done, s.allow, s.decline, s.deny.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2668
diff changeset
591 <link doc="../stream/ngx_stream_js_module.xml" id="js_preread"><literal>js_preread</literal></link>.
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
592 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
593
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
594 <tag-name id="s_error"><literal>s.error(<value>string</value>)</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
595 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
596 writes a sent <literal>string</literal> to the error log
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
597 on the <literal>error</literal> level of logging
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
598 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
599
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
600 <tag-name id="s_log"><literal>s.log(<value>string</value>)</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
601 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
602 writes a sent <value>string</value> to the error log
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
603 on the <literal>info</literal> level of logging
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
604 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
605
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
606 <tag-name id="s_off"><literal>s.off(<value>eventName</value>)</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
607 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
608 unregisters the callback set by the <link id="s_on">s.on()</link> method
2337
867fe207f13e Updated links to changes.xml in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2332
diff changeset
609 (<link doc="changes.xml" id="njs0.2.4">0.2.4</link>)
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
610 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
611
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
612 <tag-name id="s_on"><literal>s.on(<value>event</value>,
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
613 <value>callback</value>)</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
614 <tag-desc>
2579
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
615 registers a <literal>callback</literal>
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
616 for the specified <literal>event</literal>
2337
867fe207f13e Updated links to changes.xml in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2332
diff changeset
617 (<link doc="changes.xml" id="njs0.2.4">0.2.4</link>).
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
618
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
619 <para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
620 An <literal>event</literal> may be one of the following strings:
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
621 <list type="tag">
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
622 <tag-name><literal>upload</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
623 <tag-desc>
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
624 new data (string) from a client
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
625 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
626
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
627 <tag-name><literal>download</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
628 <tag-desc>
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
629 new data (string) to a client
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
630 </tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
631
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
632 <tag-name><literal>upstream</literal></tag-name>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
633 <tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
634 new data (Buffer) from a client
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
635 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
636 </tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
637
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
638 <tag-name><literal>downstream</literal></tag-name>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
639 <tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
640 new data (Buffer) to a client
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
641 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
642 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
643
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
644 </list>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
645 </para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
646
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
647 <para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
648 The completion callback has the following prototype:
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
649 <literal>callback(data, flags)</literal>, where
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
650 <literal>data</literal> is string or Buffer (depending on the event type)
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
651 <literal>flags</literal> is an object
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
652 with the following properties:
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
653 <list type="tag">
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
654 <tag-name id="s_on_callback_last"><literal>last</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
655 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
656 a boolean value, true if data is a last buffer.
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
657 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
658
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
659 </list>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
660 </para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
661 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
662
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
663 <tag-name id="s_remote_address"><literal>s.remoteAddress</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
664 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
665 client address, read-only
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
666 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
667
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
668 <tag-name id="s_raw_variables"><literal>s.rawVariables</literal></tag-name>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
669 <tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
670 nginx <link id="s_variables">variables</link> as Buffers,
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
671 writable
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
672 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
673 </tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
674
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
675 <tag-name id="s_send"><literal>s.send(<value>data</value>[,
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
676 <value>options</value>])</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
677 <tag-desc>
2667
2085eb315672 Updated description of s.send in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2666
diff changeset
678 adds data to the chain of data chunks that will be forwarded in
2085eb315672 Updated description of s.send in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2666
diff changeset
679 the forward direction:
2085eb315672 Updated description of s.send in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2666
diff changeset
680 in download callback to a client; in upload to an upstream server
2337
867fe207f13e Updated links to changes.xml in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2332
diff changeset
681 (<link doc="changes.xml" id="njs0.2.4">0.2.4</link>).
2667
2085eb315672 Updated description of s.send in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2666
diff changeset
682 The actual forwarding happens later,
2085eb315672 Updated description of s.send in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2666
diff changeset
683 when the all the data chunks of the current chain are processed.
2085eb315672 Updated description of s.send in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2666
diff changeset
684 <para>
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
685 The data can be a string or Buffer
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
686 (<link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
687 The <literal>options</literal> is an object used
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
688 to override nginx buffer flags derived from an incoming data chunk buffer.
2579
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
689 The flags can be overridden with the following flags:
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
690 <list type="tag">
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
691
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
692 <tag-name><literal>last</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
693 <tag-desc>
2579
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
694 boolean,
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
695 true if the buffer is the last buffer
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
696 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
697
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
698 <tag-name><literal>flush</literal></tag-name>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
699 <tag-desc>
2579
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
700 boolean,
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
701 true if the buffer should have the <literal>flush</literal> flag
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
702 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
703 </list>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
704 </para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
705 The method can be called multiple times per callback invocation.
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
706 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
707
2665
529114f1108a Documented s.status property in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2663
diff changeset
708 <tag-name id="s_status"><literal>s.status</literal></tag-name>
529114f1108a Documented s.status property in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2663
diff changeset
709 <tag-desc>
529114f1108a Documented s.status property in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2663
diff changeset
710 session status code, an alias to the
529114f1108a Documented s.status property in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2663
diff changeset
711 <link doc="../stream/ngx_stream_core_module.xml" id="var_status"><literal>$status</literal></link>
529114f1108a Documented s.status property in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2663
diff changeset
712 variable,
529114f1108a Documented s.status property in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2663
diff changeset
713 read only
529114f1108a Documented s.status property in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2663
diff changeset
714 (since <link doc="changes.xml" id="njs0.5.2">0.5.2</link>)
529114f1108a Documented s.status property in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2663
diff changeset
715 </tag-desc>
529114f1108a Documented s.status property in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2663
diff changeset
716
2800
3a146e49f9d4 Corrected syntax of r.setReturnValue and s.setReturnValue.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2792
diff changeset
717 <tag-name id="s_set_return_value"><literal>s.setReturnValue(<value>value</value>)</literal></tag-name>
2777
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
718 <tag-desc>
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
719 sets the return value of the
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
720 <link doc="../stream/ngx_stream_js_module.xml" id="js_set"/> handler
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
721 (<link doc="changes.xml" id="njs0.7.0">0.7.0</link>).
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
722 Unlike an ordinary return statement,
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
723 this method should be used when the handler is JS async function.
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
724 For example:
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
725 <example>
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
726 async function js_set(r) {
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
727 const digest = await crypto.subtle.digest('SHA-256', r.headersIn.host);
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
728 r.setReturnValue(digest);
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
729 }
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
730 </example>
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
731 </tag-desc>
bc79ab31073a Documented r.setReturnValue and s.setReturnValue in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2775
diff changeset
732
2338
39ac205f90b7 Documented that r.variables{} and s.variables{} are writable.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2337
diff changeset
733 <tag-name id="s_variables"><literal>s.variables{}</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
734 <tag-desc>
2338
39ac205f90b7 Documented that r.variables{} and s.variables{} are writable.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2337
diff changeset
735 nginx variables object, writable
2689
7e271437f12e Updated writable variables info in r.variables and s.variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2688
diff changeset
736 (since <link doc="changes.xml" id="njs0.2.8">0.2.8</link>).
7e271437f12e Updated writable variables info in r.variables and s.variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2688
diff changeset
737 A variable can be writable only
7e271437f12e Updated writable variables info in r.variables and s.variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2688
diff changeset
738 if it is referenced in nginx configuration file.
7e271437f12e Updated writable variables info in r.variables and s.variables.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2688
diff changeset
739 Even so, some embedded variables still cannot be assigned a value.
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
740 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
741
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
742 <tag-name id="s_warn"><literal>s.warn(<value>string</value>)</literal></tag-name>
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
743 <tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
744 writes a sent <literal>string</literal> to the error log
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
745 on the <literal>warning</literal> level of logging
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
746 </tag-desc>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
747
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
748 </list>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
749 </para>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
750
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
751 </section>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
752
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
753
2653
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
754 <section id="response" name="Response">
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
755
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
756 <para>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
757 The <literal>Response</literal> interface is available since
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
758 <link doc="changes.xml" id="njs0.5.1">0.5.1</link>.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
759
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
760 <list type="tag">
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
761
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
762 <tag-name id="response_arraybuffer"><literal>arrayBuffer()</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
763 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
764 Takes a <literal>Response</literal> stream and reads it to completion.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
765 Returns a <literal>Promise</literal> that resolves with
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
766 an <literal>ArrayBuffer</literal>.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
767 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
768
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
769 <tag-name id="response_bodyused"><literal>bodyUsed</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
770 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
771 A boolean value, <literal>true</literal>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
772 if the body was read.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
773 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
774
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
775 <tag-name id="response_headers"><literal>headers</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
776 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
777 The <literal>Headers</literal> read-only object associated with the
2668
e067ad74b0cd Corrected links to Response Object in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2667
diff changeset
778 <link id="response"><literal>Response</literal></link>:
2653
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
779
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
780 <list type="tag">
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
781
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
782 <tag-name id="headers_get"><literal>get(<value>name</value>)</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
783 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
784 returns a string containing the values of all headers with the specified name
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
785 separated by a comma and a space
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
786 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
787
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
788 <tag-name id="headers_getall"><literal>getAll(<value>name</value>)</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
789 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
790 returns an array containing the values of all headers with the specified name
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
791 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
792
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
793 <tag-name id="headers_has"><literal>has(<value>name</value>)</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
794 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
795 returns a boolean value
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
796 indicating whether a header with the specified name exists
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
797 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
798
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
799 </list>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
800 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
801
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
802 <tag-name id="response_json"><literal>json()</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
803 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
804 Takes a <literal>Response</literal> stream and reads it to completion.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
805 Returns a <literal>Promise</literal> that resolves with
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
806 the result of parsing the body text as JSON.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
807 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
808
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
809 <tag-name id="response_ok"><literal>ok</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
810 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
811 A boolean value, <literal>true</literal>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
812 if the response was successful (status codes between 200–299).
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
813 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
814
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
815 <tag-name id="response_redirect"><literal>redirected</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
816 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
817 A boolean value, <literal>true</literal>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
818 if the response is the result of a redirect.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
819 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
820
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
821 <tag-name id="response_status"><literal>status</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
822 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
823 The status code of the response.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
824 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
825
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
826 <tag-name id="response_statustext"><literal>statusText</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
827 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
828 The status message corresponding to the status code.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
829 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
830
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
831 <tag-name id="response_text"><literal>text()</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
832 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
833 Takes a <literal>Response</literal> stream and reads it to completion.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
834 Returns a <literal>Promise</literal> that resolves with a string.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
835 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
836
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
837 <tag-name id="response_type"><literal>type</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
838 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
839 The type of the response.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
840 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
841
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
842 <tag-name id="response_url"><literal>url</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
843 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
844 The URL of the response.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
845 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
846
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
847 </list>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
848 </para>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
849
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
850 </section>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
851
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
852
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
853 <section id="ngx" name="ngx">
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
854
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
855 <para>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
856 The <literal>ngx</literal> global object is available
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
857 since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>.
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
858 <list type="tag">
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
859
2653
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
860 <tag-name id="ngx_fetch"><literal>ngx.fetch(<value>url</value>,
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
861 [<value>options</value>])</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
862 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
863 Makes a request to fetch an URL
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
864 (<link doc="changes.xml" id="njs0.5.1">0.5.1</link>),
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
865 returns a <literal>Promise</literal> that resolves with
2668
e067ad74b0cd Corrected links to Response Object in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2667
diff changeset
866 the <link id="response"><literal>Response</literal></link> object.
2774
7255a5468474 Documented HTTPS support for ngx_fetch.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2735
diff changeset
867 Since <link doc="changes.xml" id="njs0.7.0">0.7.0</link>,
7255a5468474 Documented HTTPS support for ngx_fetch.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2735
diff changeset
868 the <literal>https://</literal> scheme is supported,
2653
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
869 redirects are not handled.
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
870 <para>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
871 The <literal>options</literal> parameter is expected to be an object
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
872 with the following keys:
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
873 <list type="tag">
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
874
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
875 <tag-name id="fetch_body"><literal>body</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
876 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
877 request body,
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
878 by default is empty
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
879 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
880
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
881 <tag-name id="fetch_buffer_size"><literal>buffer_size</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
882 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
883 the buffer size for reading the response,
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
884 by default is <literal>4096</literal>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
885 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
886
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
887 <tag-name id="fetch_headers"><literal>headers</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
888 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
889 request headers object
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
890 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
891
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
892 <tag-name id="fetch_get"><literal>max_response_body_size</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
893 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
894 the maximum size of the response body in bytes,
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
895 by default is <literal>32768</literal>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
896 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
897
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
898 <tag-name id="fetch_method"><literal>method</literal></tag-name>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
899 <tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
900 HTTP method,
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
901 by default the <literal>GET</literal> method is used
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
902 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
903
2775
9ce9239c6b7b Documented "verify" key in ngx_fetch.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2774
diff changeset
904 <tag-name id="fetch_verify"><literal>verify</literal></tag-name>
9ce9239c6b7b Documented "verify" key in ngx_fetch.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2774
diff changeset
905 <tag-desc>
9ce9239c6b7b Documented "verify" key in ngx_fetch.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2774
diff changeset
906 enables or disables verification of the HTTPS server certificate,
9ce9239c6b7b Documented "verify" key in ngx_fetch.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2774
diff changeset
907 by default is <literal>true</literal>
9ce9239c6b7b Documented "verify" key in ngx_fetch.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2774
diff changeset
908 (<link doc="changes.xml" id="njs0.7.0">0.7.0</link>)
9ce9239c6b7b Documented "verify" key in ngx_fetch.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2774
diff changeset
909 </tag-desc>
9ce9239c6b7b Documented "verify" key in ngx_fetch.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2774
diff changeset
910
2653
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
911 </list>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
912 Example:
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
913 <example>
2840
3b705c0a5af7 Updated example for ngx.fetch in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2818
diff changeset
914 let reply = await ngx.fetch('http://nginx.org/');
3b705c0a5af7 Updated example for ngx.fetch in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2818
diff changeset
915 let body = await reply.text();
3b705c0a5af7 Updated example for ngx.fetch in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2818
diff changeset
916
3b705c0a5af7 Updated example for ngx.fetch in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2818
diff changeset
917 r.return(200, body);
2653
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
918 </example>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
919 </para>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
920 </tag-desc>
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
921
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
922 <tag-name id="ngx_log"><literal>ngx.log</literal>(<value>level</value>,
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
923 <value>message</value>)</tag-name>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
924 <tag-desc>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
925 Writes a message to the error log with the specified level of logging.
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
926 The <value>level</value> parameter specifies one of the log levels,
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
927 the <value>message</value> parameter can be a string or Buffer.
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
928 The following log levels can be specified:
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
929 <literal>ngx.INFO</literal>,
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
930 <literal>ngx.WARN</literal>, and
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
931 <literal>ngx.ERR</literal>.
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
932 </tag-desc>
2653
9fc25ea7a92c Documented ngx.fetch and Response interface in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2647
diff changeset
933
2628
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
934 </list>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
935 </para>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
936
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
937 </section>
0ce45b4edb75 njs-0.5.0.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2612
diff changeset
938
2247
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
939 </section>
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
940
0f16ef9a8dbe Created "nginx objects" section in reference.xml.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2246
diff changeset
941
2687
7ff9d8bda757 Revised TOC in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2685
diff changeset
942 <section id="builtin_objects" name="built-in objects">
2405
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
943
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
944
2783
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
945 <section id="builtin_crypto" name="crypto">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
946
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
947 <para>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
948 The <literal>crypto</literal> object is a global object
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
949 that allows using cryptographic functionality
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
950 (since <link doc="changes.xml" id="njs0.7.0">0.7.0</link>).
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
951 </para>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
952
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
953 <para>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
954 <list type="tag">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
955
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
956 <tag-name id="crypto_get_random_values"><literal>сrypto.getRandomValues</literal>(<link id="crypto_get_random_values_array"><literal>typedArray</literal></link>)</tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
957 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
958 Gets cryptographically strong random values.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
959 Returns the same array passed as <literal>typedArray</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
960 but with its contents replaced with the newly generated random numbers.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
961 Possible values:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
962
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
963 <list type="tag">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
964 <tag-name id="crypto_get_random_values_array"><literal>typedArray</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
965 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
966 can be
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
967 <literal>Int8Array</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
968 <literal>Int16Array</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
969 <literal>Uint16Array</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
970 <literal>Int32Array</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
971 <literal>Uint32Array</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
972 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
973 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
974
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
975 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
976
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
977 <tag-name id="crypto_subtle_encrypt"><literal>сrypto.subtle.encrypt</literal>(<link id="crypto_encrypt_alg"><literal>algorithm</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
978 <link id="crypto_encrypt_key"><literal>key</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
979 <link id="crypto_encrypt_data"><literal>data</literal></link>)</tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
980 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
981 Encrypts <link id="crypto_encrypt_data"><literal>data</literal></link>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
982 using the provided
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
983 <link id="crypto_encrypt_algorithm"><literal>algorithm</literal></link> and
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
984 <link id="crypto_encrypt_key"><literal>key</literal></link>.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
985 Returns a <literal>Promise</literal> that fulfills with
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
986 an <literal>ArrayBuffer</literal> containing the ciphertext.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
987 Possible values:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
988
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
989 <list type="tag">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
990 <tag-name id="crypto_encrypt_alg"><literal>algorithm</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
991 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
992 an object that specifies
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
993 the algorithm to be used and any extra parameters if required:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
994
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
995 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
996 <listitem id="rsa_oaep_params">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
997 for <literal>RSA-OAEP</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
998 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
999
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1000 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1001
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1002 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1003 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1004 should be set to <literal>RSA-OAEP</literal>:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1005 <para>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1006 <example>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1007 crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1008 </example>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1009 </para>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1010 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1011 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1012
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1013 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1014
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1015 <listitem id="aes_ctr_params">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1016 for <literal>AES-CTR</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1017 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1018
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1019 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1020
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1021 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1022 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1023 should be set to <literal>AES-CTR</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1024 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1025
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1026 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1027 <literal>counter</literal> is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1028 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1029 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1030 <literal>DataView</literal> —
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1031 the initial value of the counter block,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1032 must be 16 bytes long (the AES block size).
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1033 The rightmost length bits of this block are used for the counter,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1034 and the rest is used for the nonce.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1035 For example, if length is set to 64,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1036 then the first half of counter is the nonce
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1037 and the second half is used for the counter
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1038 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1039
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1040 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1041 <literal>length</literal> is the number of bits in the counter block
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1042 that are used for the actual counter.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1043 The counter must be big enough that it doesn't wrap.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1044 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1045 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1046
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1047 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1048
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1049 <listitem id="aes_cbc_params">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1050 for <literal>AES-CBC</literal>, pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1051
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1052 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1053
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1054 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1055 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1056 should be set to <literal>AES-CBC</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1057 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1058
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1059 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1060 <literal>iv</literal> or the initialization vector, is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1061 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1062 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1063 <literal>DataView</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1064 must be 16 bytes, unpredictable,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1065 and preferably cryptographically random.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1066 However, it need not be secret,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1067 for example, it may be transmitted unencrypted along with the ciphertext.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1068 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1069 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1070
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1071 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1072
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1073 <listitem id="aes_gcm_params">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1074 for <literal>AES-GCM</literal>, pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1075
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1076 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1077
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1078 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1079 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1080 should be set to <literal>AES-GCM</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1081 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1082
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1083 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1084 <literal>iv</literal> or the initialization vector, is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1085 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1086 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1087 <literal>DataView</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1088 must be 16 bytes,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1089 and must be unique for every encryption operation carried out with a given key
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1090 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1091
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1092 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1093 <literal>additionalData</literal> (optional) is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1094 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1095 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1096 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1097 that contains additional data that
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1098 will not be encrypted but will be authenticated along with the encrypted data.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1099 If <literal>additionalData</literal> is specified,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1100 then the same data must be specified in the corresponding call to
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1101 <literal>decrypt()</literal>:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1102 if the data given to the <literal>decrypt()</literal> call
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1103 does not match the original data,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1104 the decryption will throw an exception.
2792
c6713b6b86ce Removed trailing spaces.
Maxim Dounin <mdounin@mdounin.ru>
parents: 2783
diff changeset
1105 The bit length of <literal>additionalData</literal>
2783
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1106 must be smaller than <literal>2^64 - 1</literal>.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1107 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1108
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1109 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1110 <literal>tagLength</literal> (optional, default is <literal>128</literal>) -
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1111 a <literal>number</literal> that determines the size in bits
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1112 of the authentication tag generated in the encryption operation
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1113 and used for authentication in the corresponding decryption
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1114 Possible values:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1115 <literal>32</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1116 <literal>64</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1117 <literal>96</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1118 <literal>104</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1119 <literal>112</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1120 <literal>120</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1121 <literal>128</literal>.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1122 The AES-GCM specification recommends that it should be
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1123 <literal>96</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1124 <literal>104</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1125 <literal>112</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1126 <literal>120</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1127 <literal>128</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1128 although
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1129 <literal>32</literal> or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1130 <literal>64</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1131 bits may be acceptable in some applications.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1132 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1133 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1134
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1135 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1136 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1137
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1138 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1139
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1140 <tag-name id="crypto_encrypt_key"><literal>key</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1141 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1142 a <literal>CryptoKey</literal> that contains
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1143 the key to be used for encryption
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1144 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1145
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1146 <tag-name id="crypto_encrypt_data"><literal>data</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1147 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1148 an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1149 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1150 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1151 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1152 that contains
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1153 the data to be encrypted (also known as the plaintext)
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1154 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1155 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1156
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1157 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1158
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1159 <tag-name id="crypto_subtle_decrypt"><literal>сrypto.subtle.decrypt</literal>(<link id="crypto_decrypt_alg"><literal>algorithm</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1160 <link id="crypto_decrypt_key"><literal>key</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1161 <link id="crypto_decrypt_data"><literal>data</literal></link>)</tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1162 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1163 Decrypts encrypted data.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1164 Returns a <literal>Promise</literal> with the decrypted data.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1165 Possible values:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1166
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1167 <list type="tag">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1168
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1169 <tag-name id="crypto_decrypt_alg"><literal>algorithm</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1170 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1171 an object
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1172 that specifies the algorithm to be used, and any extra parameters as required.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1173 The values given for the extra parameters must match
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1174 those passed into the corresponding <literal>encrypt()</literal> call.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1175
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1176 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1177 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1178 for <literal>RSA-OAEP</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1179 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1180
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1181 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1182
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1183 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1184 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1185 should be set to <literal>RSA-OAEP</literal>:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1186 <para>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1187 <example>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1188 crypto.subtle.encrypt({name: "RSA-OAEP"}, key, data)
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1189 </example>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1190 </para>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1191 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1192 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1193 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1194
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1195 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1196 for <literal>AES-CTR</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1197 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1198
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1199 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1200
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1201 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1202 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1203 should be set to <literal>AES-CTR</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1204 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1205
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1206 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1207 <literal>counter</literal> is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1208 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1209 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1210 <literal>DataView</literal> —
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1211 the initial value of the counter block,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1212 must be 16 bytes long (the AES block size).
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1213 The rightmost length bits of this block are used for the counter,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1214 and the rest is used for the nonce.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1215 For example, if length is set to 64,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1216 then the first half of counter is the nonce
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1217 and the second half is used for the counter.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1218 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1219
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1220 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1221 <literal>length</literal> is the number of bits in the counter block
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1222 that are used for the actual counter.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1223 The counter must be big enough that it doesn't wrap.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1224 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1225 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1226
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1227 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1228
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1229 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1230 for <literal>AES-CBC</literal>, pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1231
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1232 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1233
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1234 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1235 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1236 should be set to <literal>AES-CBC</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1237 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1238
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1239 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1240 <literal>iv</literal> or the initialization vector, is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1241 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1242 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1243 <literal>DataView</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1244 must be 16 bytes, unpredictable,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1245 and preferably cryptographically random.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1246 However, it need not be secret
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1247 (for example, it may be transmitted unencrypted along with the ciphertext).
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1248 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1249 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1250
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1251 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1252
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1253 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1254 for <literal>AES-GCM</literal>, pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1255
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1256 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1257
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1258 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1259 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1260 should be set to <literal>AES-GCM</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1261 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1262
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1263 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1264 <literal>iv</literal> or the initialization vector, is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1265 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1266 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1267 <literal>DataView</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1268 must be 16 bytes,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1269 and must be unique for every encryption operation carried out with a given key
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1270 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1271
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1272 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1273 <literal>additionalData</literal> (optional) is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1274 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1275 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1276 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1277 that contains additional data that
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1278 will not be encrypted but will be authenticated along with the encrypted data.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1279 If <literal>additionalData</literal> is specified,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1280 then the same data must be specified in the corresponding call to
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1281 <literal>decrypt()</literal>:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1282 if the data given to the <literal>decrypt()</literal> call
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1283 does not match the original data,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1284 the decryption will throw an exception.
2792
c6713b6b86ce Removed trailing spaces.
Maxim Dounin <mdounin@mdounin.ru>
parents: 2783
diff changeset
1285 The bit length of <literal>additionalData</literal>
2783
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1286 must be smaller than <literal>2^64 - 1</literal>.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1287 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1288
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1289 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1290 <literal>tagLength</literal> (optional, default is <literal>128</literal>) -
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1291 a <literal>number</literal> that determines the size in bits
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1292 of the authentication tag generated in the encryption operation
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1293 and used for authentication in the corresponding decryption.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1294 Possible values:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1295 <literal>32</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1296 <literal>64</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1297 <literal>96</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1298 <literal>104</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1299 <literal>112</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1300 <literal>120</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1301 <literal>128</literal>.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1302 The AES-GCM specification recommends that it should be
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1303 <literal>96</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1304 <literal>104</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1305 <literal>112</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1306 <literal>120</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1307 <literal>128</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1308 although
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1309 <literal>32</literal> or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1310 <literal>64</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1311 bits may be acceptable in some applications.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1312 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1313 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1314
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1315 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1316 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1317
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1318 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1319
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1320 <tag-name id="crypto_decrypt_key"><literal>key</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1321 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1322 a <literal>CryptoKey</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1323 that contains the key to be used for decryption.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1324 If <literal>RSA-OAEP</literal> is used, this is the
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1325 <literal>privateKey</literal> property of the
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1326 <literal>CryptoKeyPair</literal> object.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1327 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1328
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1329 <tag-name id="crypto_decrypt_data"><literal>data</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1330 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1331 an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1332 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1333 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1334 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1335 that contains the data to be decrypted (also known as ciphertext)
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1336 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1337 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1338
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1339 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1340
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1341 <tag-name id="crypto_subtle_derive_bits"><literal>сrypto.subtle.deriveBits</literal>(<link id="crypto_derive_bits_alg"><literal>algorithm</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1342 <link id="crypto_derive_bits_basekey"><literal>baseKey</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1343 <link id="crypto_derive_bits_length"><literal>length</literal></link>)</tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1344 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1345 Derives an array of bits from a base key.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1346 Returns a <literal>Promise</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1347 which will be fulfilled with an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1348 <literal>ArrayBuffer</literal> that contains the derived bits.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1349 Possible values:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1350
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1351 <list type="tag">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1352 <tag-name id="crypto_derive_bits_alg"><literal>algorithm</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1353 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1354 is an object that defines the derivation algorithm to use:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1355
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1356 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1357 <listitem id="hkdf_params">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1358 for <literal>HKDF</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1359 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1360
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1361 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1362
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1363 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1364 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1365 should be set to <literal>HKDF</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1366 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1367
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1368 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1369 <literal>hash</literal> is a string with the digest algorithm to use:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1370 <literal>SHA-1</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1371 <literal>SHA-256</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1372 <literal>SHA-384</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1373 <literal>SHA-512</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1374 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1375
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1376 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1377 <literal>salt</literal> is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1378 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1379 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1380 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1381 that represents random or pseudo-random value
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1382 with the same length as the output of the <literal>digest</literal> function.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1383 Unlike the input key material passed into <literal>deriveKey()</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1384 salt does not need to be kept secret.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1385 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1386
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1387 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1388 <literal>info</literal> is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1389 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1390 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1391 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1392 that represents application-specific contextual information
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1393 used to bind the derived key to an application or context,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1394 and enables deriving different keys for different contexts
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1395 while using the same input key material.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1396 This property is required but may be an empty buffer.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1397 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1398 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1399
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1400 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1401
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1402 <listitem id="pbkdf2_params">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1403 for <literal>PBKDF2</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1404 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1405
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1406 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1407
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1408 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1409 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1410 should be set to <literal>PBKDF2</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1411 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1412
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1413 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1414 <literal>hash</literal> is a string with the digest algorithm to use:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1415 <literal>SHA-1</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1416 <literal>SHA-256</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1417 <literal>SHA-384</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1418 <literal>SHA-512</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1419 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1420
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1421 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1422 <literal>salt</literal> is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1423 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1424 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1425 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1426 that represents random or pseudo-random value
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1427 of at least <literal>16</literal> bytes.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1428 Unlike the input key material passed into <literal>deriveKey()</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1429 salt does not need to be kept secret.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1430 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1431
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1432 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1433 <literal>iterations</literal> is a <literal>number</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1434 that represents the number of times the hash function will be executed
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1435 in <literal>deriveKey()</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1436 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1437 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1438
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1439 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1440 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1441
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1442 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1443
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1444 <tag-name id="crypto_derive_bits_basekey"><literal>baseKey</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1445 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1446 is a <literal>CryptoKey</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1447 that represents the input to the derivation algorithm
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1448 - the initial key material for the derivation function:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1449 for example, for <literal>PBKDF2</literal> it might be a password,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1450 imported as a <literal>CryptoKey</literal> using
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1451 <link id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey()</literal></link>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1452 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1453
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1454 <tag-name id="crypto_derive_bits_length"><literal>length</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1455 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1456 is a number representing the number of bits to derive.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1457 For browsers compatibility,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1458 the number should be a multiple of <literal>8</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1459 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1460 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1461
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1462 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1463
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1464 <tag-name id="crypto_subtle_derive_key"><literal>сrypto.subtle.deriveKey</literal>(<link id="crypto_derive_key_alg"><literal>algorithm</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1465 <link id="crypto_derive_key_basekey"><literal>baseKey</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1466 <link id="crypto_derive_key_derivedkeyalg"><literal>derivedKeyAlgorithm</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1467 <link id="crypto_derive_key_extractable"><literal>extractable</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1468 <link id="crypto_derive_key_keyusages"><literal>keyUsages</literal></link>)</tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1469 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1470 Derives a secret key from a master key.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1471 Possible values:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1472
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1473 <list type="tag">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1474 <tag-name id="crypto_derive_key_alg"><literal>algorithm</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1475 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1476 is an object that defines the derivation algorithm to use:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1477
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1478 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1479 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1480 for <literal>HKDF</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1481 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1482
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1483 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1484
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1485 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1486 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1487 should be set to <literal>HKDF</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1488 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1489
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1490 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1491 <literal>hash</literal> is a string with the digest algorithm to use:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1492 <literal>SHA-1</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1493 <literal>SHA-256</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1494 <literal>SHA-384</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1495 <literal>SHA-512</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1496 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1497
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1498 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1499 <literal>salt</literal> is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1500 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1501 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1502 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1503 that represents random or pseudo-random value
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1504 with the same length as the output of the <literal>digest</literal> function.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1505 Unlike the input key material passed into <literal>deriveKey()</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1506 salt does not need to be kept secret.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1507 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1508
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1509 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1510 <literal>info</literal> is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1511 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1512 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1513 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1514 that represents application-specific contextual information
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1515 used to bind the derived key to an application or context,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1516 and enables deriving different keys for different contexts
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1517 while using the same input key material.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1518 This property is required but may be an empty buffer.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1519 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1520 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1521
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1522 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1523
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1524 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1525 for <literal>PBKDF2</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1526 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1527
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1528 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1529
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1530 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1531 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1532 should be set to <literal>PBKDF2</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1533 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1534
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1535 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1536 <literal>hash</literal> is a string with the digest algorithm to use:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1537 <literal>SHA-1</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1538 <literal>SHA-256</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1539 <literal>SHA-384</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1540 <literal>SHA-512</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1541 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1542
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1543 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1544 <literal>salt</literal> is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1545 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1546 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1547 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1548 that represents random or pseudo-random value
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1549 of at least <literal>16</literal> bytes.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1550 Unlike the input key material passed into <literal>deriveKey()</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1551 salt does not need to be kept secret.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1552 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1553
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1554 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1555 <literal>iterations</literal> is a <literal>number</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1556 that represents the number of times the hash function will be executed
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1557 in <literal>deriveKey()</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1558 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1559 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1560
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1561 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1562 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1563
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1564 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1565
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1566 <tag-name id="crypto_derive_key_basekey"><literal>baseKey</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1567 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1568 is a <literal>CryptoKey</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1569 that represents the input to the derivation algorithm
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1570 - the initial key material for the derivation function:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1571 for example, for <literal>PBKDF2</literal> it might be a password,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1572 imported as a <literal>CryptoKey</literal> using
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1573 <link id="crypto_sublte_import_key"><literal>сrypto.subtle.importKey()</literal></link>.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1574 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1575
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1576 <tag-name id="crypto_derive_key_derivedkeyalg"><literal>derivedKeyAlgorithm</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1577 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1578 is an object
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1579 that defines the algorithm the derived key will be used for:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1580
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1581 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1582 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1583 for <literal>HMAC</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1584 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1585
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1586 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1587
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1588 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1589 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1590 should be set to <literal>HMAC</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1591 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1592
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1593 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1594 <literal>hash</literal> is a string with the name of the digest function to use:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1595 <literal>SHA-1</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1596 <literal>SHA-256</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1597 <literal>SHA-384</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1598 <literal>SHA-512</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1599 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1600
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1601 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1602 <literal>length</literal> (optional) is a <literal>number</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1603 that represents the length in bits of the key.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1604 If not specified, the length of the key is equal to
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1605 the block size of the chozen hash function
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1606 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1607 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1608
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1609 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1610
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1611 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1612 for
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1613 <literal>AES-CTR</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1614 <literal>AES-CBC</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1615 <literal>AES-GCM</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1616 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1617
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1618 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1619
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1620 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1621 <literal>name</literal> is a string,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1622 should be set to
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1623 <literal>AES-CTR</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1624 <literal>AES-CBC</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1625 <literal>AES-GCM</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1626 depending on the algorithm used
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1627 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1628
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1629 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1630 <literal>length</literal> is a <literal>number</literal> that represents
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1631 the length in bits of the key to generate:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1632 <literal>128</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1633 <literal>192</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1634 <literal>256</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1635 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1636 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1637
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1638 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1639 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1640
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1641 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1642
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1643 <tag-name id="crypto_derive_key_extractable"><literal>extractable</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1644 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1645 is a boolean value
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1646 that indicates whether it will be possible to export the key
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1647 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1648
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1649 <tag-name id="crypto_derive_key_keyusages"><literal>keyUsages</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1650 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1651 is an <literal>Array</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1652 that indicates what can be done with the derived key.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1653 The key usages must be allowed by the algorithm
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1654 set in <literal>derivedKeyAlgorithm</literal>.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1655 Possible values:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1656 <list type="tag">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1657
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1658 <tag-name><literal>encrypt</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1659 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1660 key for encrypting messages
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1661 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1662
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1663 <tag-name><literal>decrypt</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1664 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1665 key for decrypting messages
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1666 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1667
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1668 <tag-name><literal>sign</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1669 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1670 key for signing messages
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1671 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1672
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1673 <tag-name><literal>verify</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1674 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1675 key for verifying signatures
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1676 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1677
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1678 <tag-name><literal>deriveKey</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1679 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1680 key for deriving a new key
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1681 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1682
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1683 <tag-name><literal>deriveBits</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1684 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1685 key for deriving bits
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1686 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1687
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1688 <tag-name><literal>wrapKey</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1689 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1690 key for wrapping a key
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1691 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1692
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1693 <tag-name><literal>unwrapKey</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1694 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1695 key for unwrapping a key
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1696 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1697 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1698
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1699 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1700 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1701
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1702 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1703
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1704 <tag-name id="crypto_subtle_digest"><literal>сrypto.subtle.digest</literal>(<link id="crypto_digest_alg"><literal>algorithm</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1705 <link id="crypto_digest_data"><literal>data</literal></link>)</tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1706 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1707 Generates a digest of the given data.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1708 Takes as its arguments an identifier for the digest algorithm to use
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1709 and the data to digest.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1710 Returns a <literal>Promise</literal> which will be fulfilled with the digest.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1711 Possible values:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1712
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1713 <list type="tag">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1714 <tag-name id="crypto_digest_alg"><literal>algorithm</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1715 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1716 is a string that defines the hash function to use:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1717 <literal>SHA-1</literal> (not for cryptographic applications),
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1718 <literal>SHA-256</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1719 <literal>SHA-384</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1720 <literal>SHA-512</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1721 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1722
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1723 <tag-name id="crypto_digest_data"><literal>data</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1724 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1725 is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1726 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1727 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1728 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1729 that contains the data to be digested
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1730 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1731 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1732
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1733 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1734
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1735 <tag-name id="crypto_subtle_import_key"><literal>сrypto.subtle.importKey</literal>(<link id="crypto_import_key_format"><literal>format</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1736 <link id="crypto_import_key_keydata"><literal>keyData</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1737 <link id="crypto_import_key_alg"><literal>algorithm</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1738 <link id="crypto_import_key_extractable"><literal>extractable</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1739 <link id="crypto_import_key_keyusages"><literal>keyUsages</literal></link>)</tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1740 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1741 Imports a key: takes as input a key in an external, portable format
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1742 and gives a <literal>CryptoKey</literal> object.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1743 Returns a <literal>Promise</literal> that fulfills with the imported key
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1744 as a <literal>CryptoKey</literal> object.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1745 Possible values:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1746 <list type="tag">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1747
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1748 <tag-name id="crypto_import_key_format"><literal>format</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1749 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1750 a string that describes the data format of the key to import,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1751 can be the following:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1752 <list type="tag">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1753
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1754 <tag-name><literal>raw</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1755 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1756 the raw data format
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1757 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1758
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1759 <tag-name><literal>pkcs8</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1760 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1761 the
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1762 <link url="https://datatracker.ietf.org/doc/html/rfc5208">PKCS #8</link>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1763 format
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1764 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1765
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1766 <tag-name><literal>spki</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1767 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1768 the
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1769 <link url=" https://datatracker.ietf.org/doc/html/rfc5280#section-4.1">SubjectPublicKeyInfo</link>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1770 format
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1771 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1772
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1773 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1774
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1775 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1776
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1777 <tag-name id="crypto_import_key_keydata"><literal>keyData</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1778 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1779 the
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1780 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1781 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1782 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1783 object that contains the key in the given format
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1784 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1785
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1786 <tag-name id="crypto_import_key_alg"><literal>algorithm</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1787 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1788 a dictionary object that defines the type of key to import
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1789 and provides extra algorithm-specific parameters:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1790
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1791 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1792 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1793 for
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1794 <literal>RSASSA-PKCS1-v1_5</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1795 <literal>RSA-PSS</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1796 <literal>RSA-OAEP</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1797 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1798
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1799 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1800 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1801 <literal>name</literal> is a string, should be set to
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1802 <literal>RSASSA-PKCS1-v1_5</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1803 <literal>RSA-PSS</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1804 <literal>RSA-OAEP</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1805 depending on the used algorithm
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1806 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1807
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1808 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1809 <literal>hash</literal> is a string that represents
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1810 the name of the <literal>digest</literal> function to use, can be
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1811 <literal>SHA-256</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1812 <literal>SHA-384</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1813 <literal>SHA-512</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1814 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1815 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1816
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1817 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1818
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1819 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1820 for
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1821 <literal>ECDSA</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1822 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1823
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1824 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1825 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1826 <literal>name</literal> is a string, should be set to <literal>ECDSA</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1827 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1828
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1829 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1830 <literal>namedCurve</literal> is a string that represents
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1831 the name of the elliptic curve to use, may be
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1832 <literal>P-256</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1833 <literal>P-384</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1834 <literal>P-521</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1835 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1836
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1837 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1838 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1839
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1840 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1841 for
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1842 <literal>HMAC</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1843 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1844
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1845 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1846 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1847 <literal>name</literal> is a string, should be set to <literal>HMAC</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1848 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1849
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1850
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1851 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1852 <literal>hash</literal> is a string that represents
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1853 the name of the <literal>digest</literal> function to use, can be
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1854 <literal>SHA-256</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1855 <literal>SHA-384</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1856 <literal>SHA-512</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1857 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1858
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1859 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1860 <literal>length</literal> (optional) is a number that represents
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1861 the length in bits of the key.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1862 If omitted, the length of the key is equal to the length of the digest
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1863 generated by the chosen digest function.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1864 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1865 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1866
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1867 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1868
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1869 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1870 for
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1871 <literal>AES-CTR</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1872 <literal>AES-CBC</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1873 <literal>AES-GCM</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1874 pass the string identifying the algorithm or an object
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1875 of the form <literal>{ "name": "ALGORITHM" }</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1876 where <literal>ALGORITHM</literal> is the name of the algorithm
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1877 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1878
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1879 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1880 for
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1881 <literal>PBKDF2</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1882 pass the <literal>PBKDF2</literal> string
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1883 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1884
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1885 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1886 for
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1887 <literal>HKDF</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1888 pass the <literal>HKDF</literal> string
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1889 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1890
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1891 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1892 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1893
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1894 <tag-name id="crypto_import_key_extractable"><literal>extractable</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1895 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1896 boolean value that indicates if it is possible to export the key
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1897 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1898
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1899 <tag-name id="crypto_import_key_keyusages"><literal>keyUsages</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1900 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1901 an <literal>array</literal> that indicates possible actions with the key:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1902 <list type="tag">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1903
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1904 <tag-name><literal>encrypt</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1905 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1906 key for encrypting messages
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1907 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1908
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1909 <tag-name><literal>decrypt</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1910 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1911 key for decrypting messages
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1912 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1913
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1914 <tag-name><literal>sign</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1915 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1916 key for signing messages
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1917 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1918
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1919 <tag-name><literal>verify</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1920 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1921 key for verifying signatures
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1922 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1923
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1924 <tag-name><literal>deriveKey</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1925 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1926 key for deriving a new key
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1927 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1928
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1929 <tag-name><literal>deriveBits</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1930 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1931 key for deriving bits
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1932 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1933
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1934 <tag-name><literal>wrapKey</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1935 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1936 key for wrapping a key
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1937 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1938
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1939 <tag-name><literal>unwrapKey</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1940 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1941 key for unwrapping a key
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1942 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1943 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1944
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1945 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1946 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1947
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1948 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1949
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1950 <tag-name id="crypto_subtle_sign"><literal>сrypto.subtle.sign</literal>(<link id="crypto_sign_alg"><literal>algorithm</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1951 <link id="crypto_sign_key"><literal>key</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1952 <link id="crypto_sign_data"><literal>data</literal></link>)</tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1953 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1954 Returns <literal>signature</literal> as a <literal>Promise</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1955 that fulfills with an <literal>ArrayBuffer</literal> containing the signature.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1956 Possible values:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1957
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1958 <list type="tag">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1959 <tag-name id="crypto_sign_alg"><literal>algorithm</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1960 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1961 is a string or object that specifies the signature algorithm to use
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1962 and its parameters:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1963
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1964 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1965
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1966 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1967 for <literal>RSASSA-PKCS1-v1_5</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1968 pass the string identifying the algorithm or an object
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1969 of the form <literal>{ "name": "ALGORITHM" }</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1970 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1971
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1972 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1973 for <literal>RSA-PSS</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1974 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1975 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1976
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1977 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1978 <literal>name</literal> is a string, should be set to
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1979 <literal>RSA-PSS</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1980 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1981
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1982 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1983 <literal>saltLength</literal> is a long <literal>integer</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1984 that represents the length of the random salt to use, in bytes
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1985 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1986
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1987 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1988 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1989
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1990 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1991 for <literal>ECDSA</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1992 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1993 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1994
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1995 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1996 <literal>name</literal> is a string, should be set to
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1997 <literal>ECDSA</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1998 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
1999
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2000 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2001 <literal>hash</literal> is an identifier for the digest algorithm to use,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2002 can be
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2003 <literal>SHA-256</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2004 <literal>SHA-384</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2005 <literal>SHA-512</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2006 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2007
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2008 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2009 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2010
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2011 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2012 for <literal>HMAC</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2013 pass the string identifying the algorithm or an object
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2014 of the form <literal>{ "name": "ALGORITHM" }</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2015 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2016 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2017
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2018 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2019
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2020 <tag-name id="crypto_sign_key"><literal>key</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2021 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2022 is a <literal>CryptoKey</literal> object that the key to be used for signing.
2792
c6713b6b86ce Removed trailing spaces.
Maxim Dounin <mdounin@mdounin.ru>
parents: 2783
diff changeset
2023 If algorithm identifies a public-key cryptosystem, this is the private key.
2783
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2024 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2025
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2026 <tag-name id="crypto_sign_data"><literal>data</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2027 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2028 is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2029 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2030 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2031 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2032 object that contains the data to be signed
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2033 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2034 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2035
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2036 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2037
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2038
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2039 <tag-name id="crypto_subtle_verify"><literal>сrypto.subtle.verify</literal>(<link id="crypto_verify_alg"><literal>algorithm</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2040 <link id="crypto_verify_key"><literal>key</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2041 <link id="crypto_verify_signature"><literal>signature</literal></link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2042 <link id="crypto_verify_data"><literal>data</literal></link>)</tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2043 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2044 Verifies a digital signature,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2045 returns a <literal>Promise</literal> that fulfills with a boolean value:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2046 <literal>true</literal> if the signature is valid,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2047 otherwise <literal>false</literal>.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2048 Possible values:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2049
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2050 <list type="tag">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2051 <tag-name id="crypto_verify_alg"><literal>algorithm</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2052 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2053 is a string or object that specifies the algorithm to use
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2054 and its parameters:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2055
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2056 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2057
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2058 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2059 for <literal>RSASSA-PKCS1-v1_5</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2060 pass the string identifying the algorithm or an object
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2061 of the form <literal>{ "name": "ALGORITHM" }</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2062 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2063
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2064 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2065 for <literal>RSA-PSS</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2066 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2067 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2068
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2069 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2070 <literal>name</literal> is a string, should be set to
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2071 <literal>RSA-PSS</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2072 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2073
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2074 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2075 <literal>saltLength</literal> is a long <literal>integer</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2076 that represents the length of the random salt to use, in bytes
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2077 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2078
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2079 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2080 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2081
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2082 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2083 for <literal>ECDSA</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2084 pass the object with the following keys:
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2085 <list type="bullet">
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2086
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2087 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2088 <literal>name</literal> is a string, should be set to
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2089 <literal>ECDSA</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2090 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2091
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2092 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2093 <literal>hash</literal> is an identifier for the digest algorithm to use,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2094 can be
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2095 <literal>SHA-256</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2096 <literal>SHA-384</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2097 <literal>SHA-512</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2098 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2099
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2100 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2101 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2102
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2103 <listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2104 for <literal>HMAC</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2105 pass the string identifying the algorithm or an object
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2106 of the form <literal>{ "name": "ALGORITHM" }</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2107 </listitem>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2108 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2109
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2110 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2111
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2112 <tag-name id="crypto_verify_key"><literal>key</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2113 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2114 is a <literal>CryptoKey</literal> object that the key to be used for verifying.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2115 It is the secret key for a symmetric algorithm
2792
c6713b6b86ce Removed trailing spaces.
Maxim Dounin <mdounin@mdounin.ru>
parents: 2783
diff changeset
2116 and the public key for a public-key system.
2783
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2117 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2118
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2119 <tag-name id="crypto_verify_signature"><literal>signature</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2120 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2121 is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2122 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2123 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2124 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2125 that contains the signature to verify
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2126 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2127
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2128 <tag-name id="crypto_verify_data"><literal>data</literal></tag-name>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2129 <tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2130 is an
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2131 <literal>ArrayBuffer</literal>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2132 <literal>TypedArray</literal>, or
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2133 <literal>DataView</literal>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2134 object that contains the data whose signature is to be verified
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2135 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2136 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2137
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2138 </tag-desc>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2139
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2140 </list>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2141 </para>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2142
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2143 </section>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2144
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
2145
2666
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2146 <section id="njs" name="njs">
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2147
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2148 <para>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2149 The <literal>njs</literal> object is a global object
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2150 that represents the current VM instance
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2151 (since <link doc="changes.xml" id="njs0.2.0">0.2.0</link>).
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2152 </para>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2153
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2154 <para>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2155 <list type="tag">
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2156
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2157 <tag-name id="njs_version"><literal>njs.version</literal></tag-name>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2158 <tag-desc>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2159 Returns a string with the current version of njs
2847
f5e49925e9db Documented the njs.version_number property in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2840
diff changeset
2160 (for example, “0.7.4”).
f5e49925e9db Documented the njs.version_number property in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2840
diff changeset
2161 </tag-desc>
f5e49925e9db Documented the njs.version_number property in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2840
diff changeset
2162
f5e49925e9db Documented the njs.version_number property in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2840
diff changeset
2163 <tag-name id="njs_version_number"><literal>njs.version_number</literal></tag-name>
f5e49925e9db Documented the njs.version_number property in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2840
diff changeset
2164 <tag-desc>
f5e49925e9db Documented the njs.version_number property in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2840
diff changeset
2165 Returns a number with the current version of njs.
f5e49925e9db Documented the njs.version_number property in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2840
diff changeset
2166 For example, “0.7.4” is returned as <literal>0x000704</literal>
f5e49925e9db Documented the njs.version_number property in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2840
diff changeset
2167 (since <link doc="changes.xml" id="njs0.7.4">0.7.4</link>).
2666
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2168 </tag-desc>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2169
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2170 <tag-name id="njs_dump"><literal>njs.dump(<value>value</value>)</literal></tag-name>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2171 <tag-desc>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2172 Returns the pretty-print string representation for a value.
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2173 </tag-desc>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2174
2679
8f3e9ff2785f Corrected syntax of njs.on() and ngx.fetch() in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2670
diff changeset
2175 <tag-name id="njs_on"><literal>njs.on(<value>event</value>,
8f3e9ff2785f Corrected syntax of njs.on() and ngx.fetch() in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2670
diff changeset
2176 <value>callback</value>)</literal></tag-name>
2666
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2177 <tag-desc>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2178 Registers a callback for the specified VM event
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2179 (since <link doc="changes.xml" id="njs0.5.2">0.5.2</link>).
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2180 An event may be one of the following strings:
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2181 <list type="tag">
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2182
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2183 <tag-name><literal>exit</literal></tag-name>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2184 <tag-desc>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2185 is called before the VM is destroyed.
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2186 The callback is called without arguments.
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2187 </tag-desc>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2188
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2189 </list>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2190 </tag-desc>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2191
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2192 </list>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2193 </para>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2194
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2195 </section>
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2196
68c0566a375f Documented njs global object in njs Refernce.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2665
diff changeset
2197
2687
7ff9d8bda757 Revised TOC in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2685
diff changeset
2198 <section id="process" name="process">
2405
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2199
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2200 <para>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2201 The <literal>process</literal> object is a global object
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2202 that provides information about the current process
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2203 (<link doc="changes.xml" id="njs0.3.3">0.3.3</link>).
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2204 </para>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2205
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2206 <para>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2207 <list type="tag">
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2208
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2209 <tag-name id="process_argv"><literal>process.argv</literal></tag-name>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2210 <tag-desc>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2211 Returns an array that contains the command line arguments
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2212 passed when the current process was launched.
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2213 </tag-desc>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2214
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2215 <tag-name id="process_env"><literal>process.env</literal></tag-name>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2216 <tag-desc>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2217 Returns an object containing the user environment.
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2218 <note>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2219 By default, nginx removes all environment variables inherited
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2220 from its parent process except the TZ variable.
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2221 Use the <link doc="../ngx_core_module.xml" id="env"/> directive
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2222 to preserve some of the inherited variables.
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2223 </note>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2224 </tag-desc>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2225
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2226 <tag-name id="process_pid"><literal>process.pid</literal></tag-name>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2227 <tag-desc>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2228 Returns the PID of the current process.
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2229 </tag-desc>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2230
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2231 <tag-name id="process_ppid"><literal>process.ppid</literal></tag-name>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2232 <tag-desc>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2233 Returns the PID of the current parent process.
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2234 </tag-desc>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2235
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2236 </list>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2237 </para>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2238
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2239 </section>
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2240
dbf68c949522 Documented the "process" global object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2394
diff changeset
2241
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2242 <section id="string" name="String">
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2243
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2244 <para>
2315
ae56e4613280 Corrected language in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2313
diff changeset
2245 There are two types of strings in njs: a Unicode string (default) and
ae56e4613280 Corrected language in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2313
diff changeset
2246 a byte string.
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2247 </para>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2248
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2249 <para>
2315
ae56e4613280 Corrected language in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2313
diff changeset
2250 A Unicode string corresponds to an ECMAScript string
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2251 which contains Unicode characters.
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2252 </para>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2253
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2254 <para>
2315
ae56e4613280 Corrected language in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2313
diff changeset
2255 Byte strings contain a sequence of bytes
ae56e4613280 Corrected language in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2313
diff changeset
2256 and are used to serialize Unicode strings
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2257 to external data and deserialize from external sources.
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2258 For example, the <link id="string_toutf8">toUTF8()</link> method serializes
2688
dd2bbd104146 Unified spelling of UTF-8 in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2687
diff changeset
2259 a Unicode string to a byte string using UTF-8 encoding:
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2260 <example>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2261 >> '£'.toUTF8().toString('hex')
2688
dd2bbd104146 Unified spelling of UTF-8 in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2687
diff changeset
2262 'c2a3' /* C2 A3 is the UTF-8 representation of 00A3 ('£') code point */
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2263 </example>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2264 The <link id="string_tobytes">toBytes()</link> method serializes
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2265 a Unicode string with code points up to 255 into a byte string,
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2266 otherwise, <literal>null</literal> is returned:
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2267 <example>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2268 >> '£'.toBytes().toString('hex')
2214
e029f4bc7ede Added quotes to njs examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2212
diff changeset
2269 'a3' /* a3 is a byte equal to 00A3 ('£') code point */
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2270 </example>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2271
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2272 <list type="tag">
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2273
2211
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2274 <tag-name id="string_bytesfrom"><literal>String.bytesFrom(<value>array</value>
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2275 | <value>string</value>, <value>encoding</value>)</literal></tag-name>
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2276 <tag-desc>
2569
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
2277 Creates a byte string either from an array that contains octets,
2315
ae56e4613280 Corrected language in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2313
diff changeset
2278 or from an encoded string
2337
867fe207f13e Updated links to changes.xml in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2332
diff changeset
2279 (<link doc="changes.xml" id="njs0.2.3">0.2.3</link>).
2211
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2280 The encoding can be
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2281 <literal>hex</literal>,
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2282 <literal>base64</literal>, and
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2283 <literal>base64url</literal>.
2605
0ec1e1b063d7 Deprecated String.bytesFrom method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2604
diff changeset
2284 The method is deprecated since
0ec1e1b063d7 Deprecated String.bytesFrom method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2604
diff changeset
2285 <link doc="changes.xml" id="njs0.4.4">0.4.4</link>,
0ec1e1b063d7 Deprecated String.bytesFrom method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2604
diff changeset
2286 the <literal>Buffer.from</literal> method should be used instead:
2211
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2287 <example>
2605
0ec1e1b063d7 Deprecated String.bytesFrom method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2604
diff changeset
2288 >> Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]).toString()
2211
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2289 'buffer'
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2290
2605
0ec1e1b063d7 Deprecated String.bytesFrom method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2604
diff changeset
2291 >> Buffer.from('YnVmZmVy', 'base64').toString()
2211
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2292 'buffer'
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2293 </example>
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2294 </tag-desc>
660229c5c92f Documented String.bytesFrom() method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2207
diff changeset
2295
2267
c30048802769 Added links to njs reference from njs Compatibility.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2259
diff changeset
2296 <tag-name id="string_frombytes"><literal>String.prototype.fromBytes(<value>start</value>[,
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2297 <value>end</value>])</literal></tag-name>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2298 <tag-desc>
2569
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
2299 Returns a new Unicode string from a byte string
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2300 where each byte is replaced with a corresponding Unicode code point.
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2301 </tag-desc>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2302
2267
c30048802769 Added links to njs reference from njs Compatibility.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2259
diff changeset
2303 <tag-name id="string_fromutf8"><literal>String.prototype.fromUTF8(<value>start</value>[,
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2304 <value>end</value>])</literal></tag-name>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2305 <tag-desc>
2688
dd2bbd104146 Unified spelling of UTF-8 in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2687
diff changeset
2306 Converts a byte string containing a valid UTF-8 string
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2307 into a Unicode string,
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2308 otherwise <literal>null</literal> is returned.
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2309 </tag-desc>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2310
2579
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
2311 <tag-name id="string_tobytes"><literal>String.prototype.toBytes(<value>start</value>[,
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
2312 <value>end</value>])</literal></tag-name>
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2313 <tag-desc>
2569
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
2314 Serializes a Unicode string to a byte string.
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2315 Returns <literal>null</literal> if a character larger than 255 is
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2316 found in the string.
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2317 </tag-desc>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2318
2582
e162a71453b0 Improved String.prototype.toString() for ordinary strings in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2579
diff changeset
2319 <tag-name id="string_tostring"><literal>String.prototype.toString(<value>encoding</value>)</literal></tag-name>
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2320 <tag-desc>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2321 <para>
2582
e162a71453b0 Improved String.prototype.toString() for ordinary strings in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2579
diff changeset
2322 Encodes a string to
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2323 <literal>hex</literal>,
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2324 <literal>base64</literal>, or
2582
e162a71453b0 Improved String.prototype.toString() for ordinary strings in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2579
diff changeset
2325 <literal>base64url</literal>:
e162a71453b0 Improved String.prototype.toString() for ordinary strings in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2579
diff changeset
2326 <example>
e162a71453b0 Improved String.prototype.toString() for ordinary strings in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2579
diff changeset
2327 >> 'αβγδ'.toString('base64url')
e162a71453b0 Improved String.prototype.toString() for ordinary strings in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2579
diff changeset
2328 'zrHOss6zzrQ'
e162a71453b0 Improved String.prototype.toString() for ordinary strings in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2579
diff changeset
2329 </example>
e162a71453b0 Improved String.prototype.toString() for ordinary strings in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2579
diff changeset
2330 Before version <link doc="changes.xml" id="njs0.4.3">0.4.3</link>,
e162a71453b0 Improved String.prototype.toString() for ordinary strings in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2579
diff changeset
2331 only a <link id="string_tobytes">byte string</link> could be encoded:
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2332 <example>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2333 >> 'αβγδ'.toUTF8().toString('base64url')
2214
e029f4bc7ede Added quotes to njs examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2212
diff changeset
2334 'zrHOss6zzrQ'
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2335 </example>
2582
e162a71453b0 Improved String.prototype.toString() for ordinary strings in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2579
diff changeset
2336 </para>
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2337 </tag-desc>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2338
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2339 <tag-name id="string_toutf8"><literal>String.prototype.toUTF8(<value>start</value>[,
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2340 <value>end</value>])</literal></tag-name>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2341 <tag-desc>
2569
2edc64c05b0e Removed ECMAScript methods from njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2564
diff changeset
2342 Serializes a Unicode string
2688
dd2bbd104146 Unified spelling of UTF-8 in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2687
diff changeset
2343 to a byte string using UTF-8 encoding.
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2344 <example>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2345 >> 'αβγδ'.toUTF8().length
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2346 8
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2347 >> 'αβγδ'.length
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2348 4
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2349 </example>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2350 </tag-desc>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2351
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2352 </list>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2353 </para>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2354
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2355 </section>
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2356
2687
7ff9d8bda757 Revised TOC in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2685
diff changeset
2357 </section>
7ff9d8bda757 Revised TOC in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2685
diff changeset
2358
7ff9d8bda757 Revised TOC in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2685
diff changeset
2359
7ff9d8bda757 Revised TOC in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2685
diff changeset
2360 <section id="webapi" name="web API">
7ff9d8bda757 Revised TOC in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2685
diff changeset
2361
2186
8e2b3aadc3ce Added njs String object.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2183
diff changeset
2362
2585
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2363 <section id="textdecoder" name="Text Decoder">
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2364
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2365 <para>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2366 The <literal>TextDecoder</literal>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2367 produces a stream of code points
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2368 from a stream of bytes
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2369 (<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2370 </para>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2371
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2372 <para>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2373 <list type="tag">
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2374
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2375 <tag-name><literal>TextDecoder([[<value>encoding</value>],
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2376 <value>options</value>])</literal></tag-name>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2377 <tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2378 Creates a new <literal>TextDecoder</literal> object
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2379 for specified <literal>encoding</literal>,
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2380 currently, only UTF-8 is supported.
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2381 The <literal>options</literal> is
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2382 <literal>TextDecoderOptions</literal> dictionary with the property:
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2383
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2384 <list type="tag">
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2385
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2386 <tag-name><literal>fatal</literal></tag-name>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2387 <tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2388 boolean flag indicating if
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2389 <link id="textdecoder_decode"><literal>TextDecoder.decode()</literal></link>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2390 must throw the <value>TypeError</value> exception when
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2391 a coding error is found, by default is <literal>false</literal>.
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2392 </tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2393
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2394 </list>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2395 </tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2396
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2397 <tag-name id="textdecoder_encoding"><literal>TextDecoder.prototype.encoding</literal></tag-name>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2398 <tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2399 Returns a string with the name of the encoding used by
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2400 <link id="textdecoder"><literal>TextDecoder()</literal></link>,
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2401 read-only.
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2402 </tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2403
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2404 <tag-name id="textdecoder_fatal"><literal>TextDecoder.prototype.fatal</literal></tag-name>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2405 <tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2406 boolean flag, <literal>true</literal> if
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2407 the error mode is fatal,
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2408 read-only.
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2409 </tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2410
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2411 <tag-name id="textdecoder_ignorebom"><literal>TextDecoder.prototype.ignoreBOM</literal></tag-name>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2412 <tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2413 boolean flag, <literal>true</literal> if
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2414 the byte order marker is ignored,
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2415 read-only.
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2416 </tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2417
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2418 <tag-name id="textdecoder_decode"><literal>TextDecoder.prototype.decode(<value>buffer</value>,
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2419 [<value>options</value>])</literal></tag-name>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2420 <tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2421 Returns a string with the text
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2422 decoded from the <literal>buffer</literal> by
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2423 <link id="textdecoder"><literal>TextDecoder()</literal></link>.
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2424 The buffer can be <literal>ArrayBuffer</literal>.
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2425 The <literal>options</literal> is
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2426 <literal>TextDecodeOptions</literal> dictionary with the property:
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2427
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2428 <list type="tag">
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2429
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2430 <tag-name><literal>stream</literal></tag-name>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2431 <tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2432 boolean flag indicating if
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2433 additional data will follow in subsequent calls to <literal>decode()</literal>:
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2434 <literal>true</literal> if processing the data in chunks, and
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2435 <literal>false</literal> for the final chunk
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2436 or if the data is not chunked.
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2437 By default is <literal>false</literal>.
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2438 </tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2439
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2440 </list>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2441 <example>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2442 >> (new TextDecoder()).decode(new Uint8Array([206,177,206,178]))
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2443 αβ
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2444 </example>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2445 </tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2446
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2447 </list>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2448 </para>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2449
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2450 </section>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2451
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2452
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2453 <section id="textencoder" name="Text Encoder">
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2454
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2455 <para>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2456 The <literal>TextEncoder</literal> object
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2457 produces a byte stream with UTF-8 encoding
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2458 from a stream of code points
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2459 (<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2460 </para>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2461
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2462 <para>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2463 <list type="tag">
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2464
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2465 <tag-name><literal>TextEncoder()</literal></tag-name>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2466 <tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2467 Returns a newly constructed <literal>TextEncoder</literal>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2468 that will generate a byte stream with UTF-8 encoding.
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2469 </tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2470
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2471 <tag-name id="textencoder_encode"><literal>TextEncoder.prototype.encode(<value>string</value>)</literal></tag-name>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2472 <tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2473 Encodes <literal>string</literal> into a <literal>Uint8Array</literal>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2474 with UTF-8 encoded text.
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2475 </tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2476
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2477 <tag-name id="textencoder_encodeinto"><literal>TextEncoder.prototype.encodeInto(<value>string</value>,
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2478 <value>uint8Array</value>)</literal></tag-name>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2479 <tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2480 Encodes a <literal>string</literal> to UTF-8,
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2481 puts the result into destination <literal>Uint8Array</literal>, and
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2482 returns a dictionary object that shows the progress of the encoding.
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2483 The dictionary object contains two members:
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2484
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2485 <list type="tag">
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2486
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2487 <tag-name><literal>read</literal></tag-name>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2488 <tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2489 the number of UTF-16 units of code from the source <literal>string</literal>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2490 converted to UTF-8
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2491 </tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2492
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2493 <tag-name><literal>written</literal></tag-name>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2494 <tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2495 the number of bytes modified in the destination <literal>Uint8Array</literal>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2496 </tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2497
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2498 </list>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2499 </tag-desc>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2500
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2501 </list>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2502 </para>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2503
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2504 </section>
7035221dbe37 Documented TextDecoder and TextEncoder in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2583
diff changeset
2505
2687
7ff9d8bda757 Revised TOC in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2685
diff changeset
2506 </section>
7ff9d8bda757 Revised TOC in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2685
diff changeset
2507
7ff9d8bda757 Revised TOC in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2685
diff changeset
2508
7ff9d8bda757 Revised TOC in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2685
diff changeset
2509 <section id="njs_api_timers" name="timers">
2578
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2510
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2511 <para>
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2512 <list type="tag">
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2513
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2514 <tag-name id="cleartimeout"><literal>clearTimeout(<value>timeout</value>)</literal></tag-name>
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2515 <tag-desc>
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2516 Cancels a <literal>timeout</literal> object
2579
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
2517 created by <link id="settimeout"><literal>setTimeout()</literal></link>.
2578
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2518 </tag-desc>
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2519
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2520 <tag-name id="settimeout"><literal>setTimeout(<value>function</value>,
2579
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
2521 <value>milliseconds</value>[,
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
2522 <value>argument1</value>,
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
2523 <value>argumentN</value>])</literal></tag-name>
2578
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2524 <tag-desc>
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2525 Calls a <literal>function</literal>
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2526 after a specified number of <literal>milliseconds</literal>.
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2527 One or more optional <literal>arguments</literal>
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2528 can be passed to the specified function.
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2529 Returns a <literal>timeout</literal> object.
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2530 <example>
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2531 function handler(v)
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2532 {
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2533 // ...
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2534 }
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2535
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2536 t = setTimeout(handler, 12);
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2537
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2538 // ...
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2539
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2540 clearTimeout(t);
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2541 </example>
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2542 </tag-desc>
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2543
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2544 </list>
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2545 </para>
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2546
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2547 </section>
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2548
2687
7ff9d8bda757 Revised TOC in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2685
diff changeset
2549
7ff9d8bda757 Revised TOC in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2685
diff changeset
2550 <section id="builtin_modules" name="built-in modules">
2578
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2551
fafb7767c128 Restructured njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2571
diff changeset
2552
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2553 <section id="buffer" name="Buffer">
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2554
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2555 <para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2556 <list type="tag">
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2557
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2558 <tag-name id="buffer_alloc"><literal>Buffer.alloc(<value>size</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2559 <value>fill</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2560 <value>encoding</value>]]))</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2561 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2562 <para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2563 Allocates a new Buffer of a specified <value>size</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2564 If <value>fill</value> is not specified, the Buffer will be zero-filled.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2565 If <value>fill</value> is specified,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2566 the allocated Buffer will be initialized by calling
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2567 <link id="buf_fill"><literal>buf.fill(fill)</literal></link>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2568 If <value>fill</value> and <value>encoding</value> are specified,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2569 the allocated Buffer will be initialized by calling
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2570 <link id="buf_fill"><literal>buf.fill(fill,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2571 encoding)</literal></link>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2572 </para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2573
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2574 <para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2575 The <value>fill</value> parameter may be a
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2576 <value>string</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2577 <value>Buffer</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2578 <value>Uint8Array</value>, or
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2579 <value>integer</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2580 </para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2581 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2582
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2583 <tag-name id="buffer_alloc_unsafe"><literal>Buffer.allocUnsafe(<value>size</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2584 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2585 <para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2586 The same as
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2587 <link id="buffer_alloc"><literal>Buffer.alloc()</literal></link>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2588 with the difference that the memory allocated for the buffer is not initialized,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2589 the contents of the new buffer is unknown and may contain sensitive data.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2590 </para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2591 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2592
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2593 <tag-name id="buffer_bytelength"><literal>Buffer.byteLength(<value>value</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2594 <value>encoding</value>])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2595 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2596 Returns the byte length of a specified value,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2597 when encoded using <value>encoding</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2598 The value can be a
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2599 <literal>string</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2600 <literal>Buffer</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2601 <literal>TypedArray</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2602 <literal>DataView</literal>, or
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2603 <literal>ArrayBuffer</literal>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2604 If the value is a <value>string</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2605 the <literal>encoding</literal> parameter is its encoding, can be
2631
7da360f50017 Unified spelling of "utf-8" in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2630
diff changeset
2606 <value>utf8</value>,
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2607 <value>hex</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2608 <value>base64</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2609 <value>base64url</value>;
2631
7da360f50017 Unified spelling of "utf-8" in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2630
diff changeset
2610 by default is <value>utf8</value>.
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2611 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2612
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2613 <tag-name id="buffer_compare"><literal>Buffer.compare(<value>buffer1</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2614 <value>buffer2</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2615 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2616 Compares <value>buffer1</value> with <value>buffer2</value>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2617 when sorting arrays of Buffer instances.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2618 Returns
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2619 <literal>0</literal> if
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2620 <value>buffer1</value> is the same as <value>buffer2</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2621 <literal>1</literal> if
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2622 <value>buffer2</value> should come before <value>buffer1</value> when sorted, or
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2623 <literal>-1</literal> if
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2624 <value>buffer2</value> should come after <value>buffer1</value> when sorted.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2625 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2626
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2627 <tag-name id="buffer_concat"><literal>Buffer.concat(<value>list</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2628 <value>totalLength</value>])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2629 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2630 Returns a new Buffer
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2631 which is the result of concatenating all the Buffer instances in the list.
2735
ff357b676c2e Removed trailing spaces.
Maxim Dounin <mdounin@mdounin.ru>
parents: 2716
diff changeset
2632 If there are no items in the list or the total length is 0,
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2633 a new zero-length Buffer is returned.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2634 If <value>totalLength</value> is not specified,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2635 it is calculated from the Buffer instances in list by adding their lengths.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2636 If <value>totalLength</value> is specified,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2637 it is coerced to an unsigned integer.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2638 If the combined length of the Buffers in list exceeds
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2639 <value>totalLength</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2640 the result is truncated to <value>totalLength</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2641 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2642
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2643 <tag-name id="buffer_from_array"><literal>Buffer.from(<value>array</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2644 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2645 Allocates a new Buffer using an array of bytes
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2646 in the range <literal>0</literal> – <literal>255</literal>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2647 Array entries outside that range will be truncated.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2648 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2649
2612
6fdefb00858f Documented Buffer.from(arrayBuffer) method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2609
diff changeset
2650 <tag-name id="buffer_from_arraybuffer"><literal>Buffer.from(<value>arrayBuffer</value>,
6fdefb00858f Documented Buffer.from(arrayBuffer) method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2609
diff changeset
2651 <value>byteOffset</value>[,
6fdefb00858f Documented Buffer.from(arrayBuffer) method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2609
diff changeset
2652 <value>length</value>]])</literal></tag-name>
6fdefb00858f Documented Buffer.from(arrayBuffer) method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2609
diff changeset
2653 <tag-desc>
6fdefb00858f Documented Buffer.from(arrayBuffer) method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2609
diff changeset
2654 Creates a view of the <value>ArrayBuffer</value>
6fdefb00858f Documented Buffer.from(arrayBuffer) method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2609
diff changeset
2655 without copying the underlying memory.
6fdefb00858f Documented Buffer.from(arrayBuffer) method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2609
diff changeset
2656 The optional <value>byteOffset</value> and <value>length</value> arguments
6fdefb00858f Documented Buffer.from(arrayBuffer) method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2609
diff changeset
2657 specify a memory range within the <value>arrayBuffer</value>
6fdefb00858f Documented Buffer.from(arrayBuffer) method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2609
diff changeset
2658 that will be shared by the Buffer.
6fdefb00858f Documented Buffer.from(arrayBuffer) method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2609
diff changeset
2659 </tag-desc>
6fdefb00858f Documented Buffer.from(arrayBuffer) method in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2609
diff changeset
2660
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2661 <tag-name id="buffer_from_buffer"><literal>Buffer.from(<value>buffer</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2662 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2663 Copies the passed buffer data onto a new Buffer instance.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2664 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2665
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2666 <tag-name id="buffer_from_object"><literal>Buffer.from(<value>object</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2667 <value>offsetOrEncoding</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2668 <value>length</value>]])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2669 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2670 For objects whose <literal>valueOf()</literal> function
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2671 returns a value not strictly equal to object,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2672 returns
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2673 <literal>Buffer.from(object.valueOf()</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2674 <literal>offsetOrEncoding</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2675 <literal>length</literal>).
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2676 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2677
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2678 <tag-name id="buffer_from_string"><literal>Buffer.from(<value>string</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2679 <value>encoding</value>])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2680 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2681 Creates a new Buffer with a <value>string</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2682 The <value>encoding</value> parameter identifies the character encoding
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2683 to be used when converting a string into bytes.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2684 The encoding can be
2631
7da360f50017 Unified spelling of "utf-8" in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2630
diff changeset
2685 <literal>utf8</literal>,
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2686 <literal>hex</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2687 <literal>base64</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2688 <literal>base64url</literal>;
2631
7da360f50017 Unified spelling of "utf-8" in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2630
diff changeset
2689 by default is <literal>utf8</literal>.
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2690 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2691
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2692 <tag-name id="buffer_is_buffer"><literal>Buffer.isBuffer(<value>object</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2693 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2694 A boolean value,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2695 returns <literal>true</literal> if <value>object</value> is a Buffer.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2696 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2697
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2698 <tag-name id="buffer_is_encoding"><literal>Buffer.isEncoding(<value>encoding</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2699 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2700 A boolean value,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2701 returns <literal>true</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2702 if encoding is the name of a supported character encoding.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2703 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2704
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2705 <tag-name id="buf_index"><literal>buffer[<value>index</value>]</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2706 <tag-desc>
2647
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2707 The index operator that can be used to get and set the octet
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2708 at position <literal>index</literal> in <literal>buffer</literal>.
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2709 The values refer to individual bytes,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2710 so the legal value range is between 0 and 255 (decimal).
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2711 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2712
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2713 <tag-name id="buf_buffer"><literal>buf.buffer</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2714 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2715 The underlying <literal>ArrayBuffer</literal> object
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2716 based on which this Buffer object is created.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2717 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2718
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2719 <tag-name id="buf_byte_offset"><literal>buf.byteOffset</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2720 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2721 An integer,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2722 specifying the <literal>byteOffset</literal> of the Buffers
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2723 underlying <literal>ArrayBuffer</literal> object.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2724 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2725
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2726 <tag-name id="buf_compare"><literal>buf.compare(<value>target</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2727 <value>targetStart</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2728 <value>targetEnd</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2729 <value>sourceStart</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2730 <value>sourceEnd</value>]]]])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2731 <tag-desc>
2647
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2732 Compares buffer with <value>target</value> and returns a number
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2733 indicating whether buffer comes before, after, or is the same
2647
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2734 as <value>target</value> in sort order.
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2735 Comparison is based on the actual sequence of bytes in each Buffer.
2647
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2736 The <literal>targetStart</literal> is an integer specifying
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2737 the offset within <value>target</value> at which to begin comparison,
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2738 by default is 0.
2647
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2739 The <literal>targetEnd</literal> is an integer specifying
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2740 the offset within <value>target</value> at which to end comparison,
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2741 by default is <literal>target.length</literal>.
2647
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2742 The <literal>sourceStart</literal> is an integer specifying
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2743 the offset within buffer at which to begin comparison,
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2744 by default is 0.
2647
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2745 The <literal>sourceEnd</literal> is an integer specifying
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2746 the offset within buffer at which to end comparison (not inclusive),
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2747 by default is <literal>buf.length</literal>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2748 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2749
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2750 <tag-name id="buf_copy"><literal>buf.copy(<value>target</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2751 <value>targetStart</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2752 <value>sourceStart</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2753 <value>sourceEnd</value>]]])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2754 <tag-desc>
2647
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2755 Copies data from a region of buffer to a region in <value>target</value>,
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2756 even if the target memory region overlaps with buffer.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2757 The <literal>target</literal> parameter is a
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2758 <value>Buffer</value> or <value>Uint8Array</value> to copy into.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2759
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2760 <para>
2647
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2761 The <literal>targetStart</literal> is an integer specifying
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2762 the offset within target at which to begin writing,
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2763 by default is 0.
2647
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2764 The <literal>sourceStart</literal> is an integer specifying
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2765 the offset within buffer from which to begin copying,
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2766 by default is 0.
2647
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2767 The <literal>sourceEnd</literal> is an integer specifying
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
2768 the offset within buffer at which to stop copying (not inclusive)
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2769 by default is <value>buf.length</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2770 </para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2771 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2772
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2773 <tag-name id="buf_equals"><literal>buf.equals(<value>otherBuffer</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2774 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2775 A boolean value,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2776 returns <literal>true</literal> if both Buffer and <value>otherBuffer</value>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2777 have exactly the same bytes.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2778 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2779
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2780 <tag-name id="buf_fill"><literal>buf.fill(<value>value</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2781 <value>offset</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2782 <value>end</value>]][,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2783 <value>encoding</value>])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2784 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2785 Fills the Buffer with the specified <value>value</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2786 If the <value>offset</value> and <value>end</value> are not specified,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2787 the entire Buffer will be filled.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2788 The <value>value</value> is coerced to <value>uint32</value> if it is not a
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2789 <literal>string</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2790 <literal>Buffer</literal>, or
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2791 <literal>integer</literal>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2792 If the resulting integer is greater than 255,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2793 the Buffer will be filled with <value>value</value> and 255.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2794 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2795
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2796 <tag-name id="buf_includes"><literal>buf.includes(<value>value</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2797 <value>byteOffset</value>][,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2798 <value>encoding</value>])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2799 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2800 Equivalent to
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2801 <link id="buf_indexof"><literal>buf.indexOf()</literal></link>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2802 <literal>!== -1</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2803 returns <literal>true</literal> if the <value>value</value> was found
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2804 in Buffer.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2805 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2806
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2807 <tag-name id="buf_indexof"><literal>buf.indexOf(<value>value</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2808 <value>byteOffset</value>][,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2809 <value>encoding</value>])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2810 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2811 Returns an integer which is the index of the first occurrence of
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2812 <value>value</value> in Buffer, or <value>-1</value>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2813 if Buffer does not contain value.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2814 The <value>value</value> can be a
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2815 <literal>string</literal> with specified <value>encoding</value>
2631
7da360f50017 Unified spelling of "utf-8" in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2630
diff changeset
2816 (by default <value>utf8</value>),
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2817 <literal>Buffer</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2818 <literal>Unit8Array</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2819 or a number between 0 and 255.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2820 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2821
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2822 <tag-name id="buf_lastindexof"><literal>buf.lastIndexOf(<value>value</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2823 <value>byteOffset</value>][,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2824 <value>encoding</value>])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2825 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2826 The same as
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2827 <link id="buf_indexof"><literal>buf.indexOf()</literal></link>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2828 except the last occurrence of the <value>value</value> is found
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2829 instead of the first occurrence.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2830 The <value>value</value> can be a string, Buffer, or
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2831 integer between 1 and 255.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2832 If the <value>value</value> is an empty string or empty Buffer,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2833 <literal>byteOffset</literal> will be returned.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2834 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2835
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2836 <tag-name id="buf_length"><literal>buf.length</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2837 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2838 Returns the number of bytes in Buffer.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2839 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2840
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2841 <tag-name id="buf_readintbe"><literal>buf.readIntBE(<value>offset</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2842 <value>byteLength</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2843 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2844 Reads the <value>byteLength</value> from <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2845 at the specified <value>offset</value>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2846 and interprets the result as a big-endian,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2847 two's complement signed value supporting up to 48 bits of accuracy.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2848 The <value>byteLength</value> parameter is an integer between 1 and 6
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2849 specifying the number of bytes to read.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2850 <para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2851 The similar methods are also supported:
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2852 <literal>buf.readInt8([offset])</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2853 <literal>buf.readInt16BE([offset])</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2854 <literal>buf.readInt32BE([offset])</literal>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2855 </para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2856 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2857
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2858 <tag-name id="buf_readintle"><literal>buf.readIntLE(<value>offset</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2859 <value>byteLength</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2860 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2861 Reads the <value>byteLength</value> from <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2862 at the specified <value>offset</value>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2863 and interprets the result as a little-endian,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2864 two's complement signed value supporting up to 48 bits of accuracy.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2865 The <value>byteLength</value> parameter is an integer between 1 and 6
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2866 specifying the number of bytes to read.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2867 <para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2868 The similar methods are also supported:
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2869 <literal>buf.readInt8([offset])</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2870 <literal>buf.readInt16LE([offset])</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2871 <literal>buf.readInt32LE([offset])</literal>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2872 </para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2873 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2874
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2875 <tag-name id="buf_readuintbe"><literal>buf.readUIntBE(<value>offset</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2876 <value>byteLength</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2877 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2878 Reads the <value>byteLength</value> from <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2879 at the specified <value>offset</value>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2880 and interprets the result as a big-endian
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2881 integer supporting up to 48 bits of accuracy.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2882 The <value>byteLength</value> parameter is an integer between 1 and 6
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2883 specifying the number of bytes to read.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2884 <para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2885 The similar methods are also supported:
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2886 <literal>buf.readUInt8([offset])</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2887 <literal>buf.readUInt16BE([offset])</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2888 <literal>buf.readUInt32BE([offset])</literal>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2889 </para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2890 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2891
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2892 <tag-name id="buf_readuintle"><literal>buf.readUIntLE(<value>offset</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2893 <value>byteLength</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2894 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2895 Reads the <value>byteLength</value> from <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2896 at the specified <value>offset</value>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2897 and interprets the result as a little-endian
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2898 integer supporting up to 48 bits of accuracy.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2899 The <value>byteLength</value> parameter is an integer between 1 and 6
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2900 specifying the number of bytes to read.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2901 <para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2902 The similar methods are also supported:
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2903 <literal>buf.readUInt8([offset])</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2904 <literal>buf.readUInt16LE([offset])</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2905 <literal>buf.readUInt32LE([offset])</literal>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2906 </para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2907 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2908
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2909 <tag-name id="buf_readdobulebe"><literal>buf.readDoubleBE</literal>([<value>offset</value>])</tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2910 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2911 Reads a 64-bit, big-endian double from <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2912 at the specified <value>offset</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2913 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2914
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2915 <tag-name id="buf_readdobulele"><literal>buf.readDoubleLE</literal>([<value>offset</value>])</tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2916 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2917 Reads a 64-bit, little-endian double from <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2918 at the specified <value>offset</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2919 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2920
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2921 <tag-name id="buf_readfloatbe"><literal>buf.readFloatBE</literal>([<value>offset</value>])</tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2922 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2923 Reads a 32-bit, big-endian float from <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2924 at the specified <value>offset</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2925 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2926
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2927 <tag-name id="buf_readfloatle"><literal>buf.readFloatLE</literal>([<value>offset</value>])</tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2928 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2929 Reads a 32-bit, little-endian float from <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2930 at the specified <value>offset</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2931 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2932
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2933 <tag-name id="buf_subarray"><literal>buf.subarray[<value>start</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2934 <value>end</value>]])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2935 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2936 Returns a new <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2937 that references the same memory as the original,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2938 but offset and cropped by
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2939 <value>start</value> and <value>end</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2940 If <value>end</value> is greater than
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2941 <link id="buf_length"><literal>buf.length</literal></link>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2942 the same result as that of end equal to
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2943 <link id="buf_length"><literal>buf.length</literal></link>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2944 is returned.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2945 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2946
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2947 <tag-name id="buf_slice"><literal>buf.slice[<value>start</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2948 <value>end</value>]])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2949 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2950 Returns a new <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2951 that references the same memory as the original,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2952 but offset and cropped by the
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2953 <value>start</value> and <value>end</value> values.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2954 The method is not compatible with the
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2955 <literal>Uint8Array.prototype.slice()</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2956 which is a superclass of Buffer.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2957 To copy the slice, use
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2958 <literal>Uint8Array.prototype.slice()</literal>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2959 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2960
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2961 <tag-name id="buf_swap16"><literal>buf.swap16</literal>()</tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2962 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2963 Interprets <literal>buf</literal> as an array of unsigned 16-bit numbers
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2964 and swaps the byte order in-place.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2965 Throws an error if
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2966 <link id="buf_length"><literal>buf.length</literal></link>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2967 is not a multiple of 2.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2968 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2969
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2970 <tag-name id="buf_swap32"><literal>buf.swap32</literal>()</tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2971 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2972 Interprets <literal>buf</literal> as an array of unsigned 32-bit numbers
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2973 and swaps the byte order in-place.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2974 Throws an error if
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2975 <link id="buf_length"><literal>buf.length</literal></link>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2976 is not a multiple of 4.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2977 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2978
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2979 <tag-name id="buf_swap64"><literal>buf.swap64</literal>()</tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2980 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2981 Interprets <literal>buf</literal> as an array of 64-bit numbers
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2982 and swaps byte order in-place.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2983 Throws an error if
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2984 <link id="buf_length"><literal>buf.length</literal></link>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2985 is not a multiple of 8.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2986 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2987
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2988 <tag-name id="buf_tojson"><literal>buf.toJSON</literal>()</tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2989 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2990 Returns a JSON representation of <literal>buf.</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2991 <literal>JSON.stringify()</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2992 implicitly calls this function when stringifying a Buffer instance.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2993 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2994
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2995 <tag-name id="buf_tostring"><literal>buf.toString([<value>encoding</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2996 <value>start</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2997 <value>end</value>]]])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2998 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
2999 Decodes <literal>buf</literal> to a string
2647
0085d9f7dc3f Minor corrections in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2631
diff changeset
3000 according to the specified character <value>encoding</value>
2631
7da360f50017 Unified spelling of "utf-8" in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2630
diff changeset
3001 which can be <value>utf8</value>,
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3002 <value>hex</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3003 <value>base64</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3004 <value>base64url</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3005 The <value>start</value> and <value>end</value> parameters
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3006 may be passed to decode only a subset of Buffer.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3007 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3008
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3009 <tag-name id="buf_write"><literal>buf.write(<value>string</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3010 <value>offset</value>[,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3011 <value>length</value>]][,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3012 <value>encoding</value>])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3013 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3014 Writes a <value>string</value> to <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3015 at <value>offset</value>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3016 according to the character <value>encoding</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3017 The <value>length</value> parameter is the number of bytes to write.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3018 If Buffer did not contain enough space to fit the entire string,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3019 only part of string will be written,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3020 however, partially encoded characters will not be written.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3021 The <value>encoding</value> can be
2631
7da360f50017 Unified spelling of "utf-8" in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2630
diff changeset
3022 <value>utf8</value>,
2609
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3023 <value>hex</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3024 <value>base64</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3025 <value>base64url</value>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3026 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3027
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3028 <tag-name id="buf_writeintbe"><literal>buf.writeIntBE(<value>value</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3029 <value>offset</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3030 <value>byteLength</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3031 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3032 Writes <value>byteLength</value> bytes of <value>value</value>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3033 to <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3034 at the specified <value>offset</value> as big-endian.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3035 Supports up to 48 bits of accuracy.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3036 The <value>byteLength</value> parameter is an integer between 1 and 6
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3037 specifying the number of bytes to read.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3038 <para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3039 The following similar methods are also supported:
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3040 <literal>buf.writeInt8</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3041 <literal>buf.writeInt16BE</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3042 <literal>buf.writeInt32BE</literal>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3043 </para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3044 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3045
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3046 <tag-name id="buf_writeintle"><literal>buf.writeIntLE(<value>value</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3047 <value>offset</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3048 <value>byteLength</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3049 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3050 Writes <value>byteLength</value> bytes of <value>value</value>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3051 to <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3052 at the specified <value>offset</value> as little-endian.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3053 Supports up to 48 bits of accuracy.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3054 The <value>byteLength</value> parameter is an integer between 1 and 6
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3055 specifying the number of bytes to read.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3056 <para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3057 The following similar methods are also supported:
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3058 <literal>buf.writeInt8</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3059 <literal>buf.writeInt16LE</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3060 <literal>buf.writeInt32LE</literal>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3061 </para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3062 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3063
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3064 <tag-name id="buf_writeuintbe"><literal>buf.writeUIntBE(<value>value</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3065 <value>offset</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3066 <value>byteLength</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3067 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3068 Writes <value>byteLength</value> bytes of <value>value</value>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3069 to <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3070 at the specified <value>offset</value> as big-endian.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3071 Supports up to 48 bits of accuracy.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3072 The <value>byteLength</value> parameter is an integer between 1 and 6
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3073 specifying the number of bytes to read.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3074 <para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3075 The following similar methods are also supported:
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3076 <literal>buf.writeUInt8</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3077 <literal>buf.writeUInt16BE</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3078 <literal>buf.writeUInt32BE</literal>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3079 </para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3080 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3081
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3082 <tag-name id="buf_writeuintle"><literal>buf.writeUIntLE(<value>value</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3083 <value>offset</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3084 <value>byteLength</value>)</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3085 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3086 Writes <value>byteLength</value> bytes of <value>value</value>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3087 to <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3088 at the specified <value>offset</value> as little-endian.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3089 Supports up to 48 bits of accuracy.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3090 The <value>byteLength</value> parameter is an integer between 1 and 6
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3091 specifying the number of bytes to read.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3092 <para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3093 The following similar methods are also supported:
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3094 <literal>buf.writeUInt8</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3095 <literal>buf.writeUInt16LE</literal>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3096 <literal>buf.writeUInt32LE</literal>.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3097 </para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3098 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3099
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3100 <tag-name id="buf_writedoublebe"><literal>buf.writeDoubleBE(<value>value</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3101 [<value>offset</value>])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3102 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3103 Writes the <value>value</value> to <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3104 at the specified <value>offset</value> as big-endian.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3105 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3106
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3107 <tag-name id="buf_writedoublele"><literal>buf.writeDoubleLE(<value>value</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3108 [<value>offset</value>])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3109 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3110 Writes the <value>value</value> to <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3111 at the specified <value>offset</value> as little-endian.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3112 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3113
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3114 <tag-name id="buf_writefloatbe"><literal>buf.writeFloatBE(<value>value</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3115 [<value>offset</value>])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3116 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3117 Writes the <value>value</value> to <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3118 at the specified <value>offset</value> as big-endian.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3119 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3120
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3121 <tag-name id="buf_writefloatle"><literal>buf.writeFloatLE(<value>value</value>,
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3122 [<value>offset</value>])</literal></tag-name>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3123 <tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3124 Writes the <value>value</value> to <literal>buf</literal>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3125 at the specified <value>offset</value> as little-endian.
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3126 </tag-desc>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3127
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3128 </list>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3129 </para>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3130
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3131 </section>
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3132
99bd2ae8d2be Added Buffer to njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2605
diff changeset
3133
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3134 <section id="crypto" name="Crypto">
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3135
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3136 <para>
2783
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
3137 <note>
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
3138 Since <link doc="changes.xml" id="njs0.7.0">0.7.0</link>,
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
3139 extended crypto API is available as a global
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
3140 <link id="builtin_crypto">crypto</link> object.
87713cb4be56 Documented WebCrypto API for njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2777
diff changeset
3141 </note>
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3142 The Crypto module provides cryptographic functionality support.
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3143 The Crypto module object is returned by <literal>require('crypto')</literal>.
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3144 </para>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3145
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3146 <para>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3147 <list type="tag">
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3148
2267
c30048802769 Added links to njs reference from njs Compatibility.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2259
diff changeset
3149 <tag-name id="crypto_createhash"><literal>crypto.createHash(<value>algorithm</value>)</literal></tag-name>
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3150 <tag-desc>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3151 Creates and returns a <link id="crypto_hash">Hash</link> object
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3152 that can be used to generate hash digests
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3153 using the given <value>algorithm</value>.
2496
9dddac1420fe Fixed typo in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2484
diff changeset
3154 The algorithm can be
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3155 <literal>md5</literal>,
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3156 <literal>sha1</literal>, and
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3157 <literal>sha256</literal>.
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3158 </tag-desc>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3159
2267
c30048802769 Added links to njs reference from njs Compatibility.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2259
diff changeset
3160 <tag-name id="crypto_createhmac"><literal>crypto.createHmac(<value>algorithm</value>,
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3161 <value>secret key</value>)</literal></tag-name>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3162 <tag-desc>
2579
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
3163 Creates and returns an <link id="crypto_hmac">HMAC</link> object that uses
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
3164 the given <value>algorithm</value> and <value>secret key</value>.
2496
9dddac1420fe Fixed typo in njs reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2484
diff changeset
3165 The algorithm can be
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3166 <literal>md5</literal>,
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3167 <literal>sha1</literal>, and
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3168 <literal>sha256</literal>.
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3169 </tag-desc>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3170
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3171 </list>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3172 </para>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3173
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3174
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3175 <section id="crypto_hash" name="Hash">
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3176
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3177 <para>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3178 <list type="tag">
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3179
2601
5528961da54d njs-0.4.4.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2585
diff changeset
3180 <tag-name id="crypto_hash_update"><literal>hash.update(<value>data</value>)</literal></tag-name>
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3181 <tag-desc>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3182 Updates the hash content with the given <value>data</value>.
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3183 </tag-desc>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3184
2601
5528961da54d njs-0.4.4.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2585
diff changeset
3185 <tag-name id="crypto_hash_digest"><literal>hash.digest([<value>encoding</value>])</literal></tag-name>
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3186 <tag-desc>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3187 Calculates the digest of all of the data passed using
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3188 <literal>hash.update()</literal>.
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3189 The encoding can be
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3190 <literal>hex</literal>,
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3191 <literal>base64</literal>, and
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3192 <literal>base64url</literal>.
2604
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3193 If encoding is not provided, a Buffer object
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3194 (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>) is returned.
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3195 <note>
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3196 Before version (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3197 a byte string was returned instead of a Buffer object.
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3198 </note>
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3199 </tag-desc>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3200
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3201 </list>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3202 </para>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3203
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3204 <para>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3205 <example>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3206 >> var cr = require('crypto')
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3207 undefined
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3208
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3209 >> cr.createHash('sha1').update('A').update('B').digest('base64url')
2214
e029f4bc7ede Added quotes to njs examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2212
diff changeset
3210 'BtlFlCqiamG-GMPiK_GbvKjdK10'
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3211 </example>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3212 </para>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3213
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3214 </section>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3215
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3216
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3217 <section id="crypto_hmac" name="HMAC">
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3218
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3219 <para>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3220 <list type="tag">
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3221
2601
5528961da54d njs-0.4.4.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2585
diff changeset
3222 <tag-name id="crypto_hmac_update"><literal>hmac.update(<value>data</value>)</literal></tag-name>
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3223 <tag-desc>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3224 Updates the HMAC content with the given <value>data</value>.
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3225 </tag-desc>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3226
2601
5528961da54d njs-0.4.4.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2585
diff changeset
3227 <tag-name id="crypto_hmac_digest"><literal>hmac.digest([<value>encoding</value>])</literal></tag-name>
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3228 <tag-desc>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3229 Calculates the HMAC digest of all of the data passed using
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3230 <literal>hmac.update()</literal>.
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3231 The encoding can be
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3232 <literal>hex</literal>,
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3233 <literal>base64</literal>, and
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3234 <literal>base64url</literal>.
2604
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3235 If encoding is not provided, a Buffer object
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3236 (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>) is returned.
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3237 <note>
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3238 Before version <link doc="changes.xml" id="njs0.4.4">0.4.4</link>,
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3239 a byte string was returned instead of a Buffer object.
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3240 </note>
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3241 </tag-desc>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3242 </list>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3243 </para>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3244
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3245 <para>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3246 <example>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3247 >> var cr = require('crypto')
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3248 undefined
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3249
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3250 >> cr.createHmac('sha1', 'secret.key').update('AB').digest('base64url')
2214
e029f4bc7ede Added quotes to njs examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2212
diff changeset
3251 'Oglm93xn23_MkiaEq_e9u8zk374'
2177
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3252 </example>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3253 </para>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3254
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3255 </section>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3256
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3257 </section>
79297494d291 Added njs Crypto API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2176
diff changeset
3258
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3259
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3260 <section id="njs_api_fs" name="File System">
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3261
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3262 <para>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3263 The File System module provides operations with files.
2507
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3264 </para>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3265
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3266 <para>
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3267 The module object is returned by <literal>require('fs')</literal>.
2508
d3d5b67a1462 Language fixes in njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2507
diff changeset
3268 Since <link doc="changes.xml" id="njs0.3.9">0.3.9</link>,
d3d5b67a1462 Language fixes in njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2507
diff changeset
3269 promissified versions of file system methods are available through
2507
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3270 <literal>require('fs').promises</literal> object:
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3271 <example>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3272 > var fs = require('fs').promises;
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3273 undefined
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3274 > fs.readFile("/file/path").then((data)=>console.log(data))
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3275 &lt;file data&gt;
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3276 </example>
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3277 <list type="tag">
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3278
2507
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3279 <tag-name id="fs_accesssync"><literal>accessSync(<value>path</value>[,
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3280 <value>mode</value>])</literal></tag-name>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3281 <tag-desc>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3282 Synchronously tests permissions for a file or directory
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3283 specified in the <literal>path</literal>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3284 (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3285 If the check fails, an error will be returned,
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3286 otherwise, the method will return undefined.
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3287 <list type="tag">
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3288
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3289 <tag-name><literal>mode</literal></tag-name>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3290 <tag-desc>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3291 by default is <link id="access_const"><literal>fs.constants.F_OK</literal></link>.
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3292 The mode argument is an optional integer
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3293 that specifies the accessibility checks to be performed.
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3294 <example>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3295 try {
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3296 fs.accessSync('/file/path', fs.constants.R_OK | fs.constants.W_OK);
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3297 console.log('has access');
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3298 } catch (e) {
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3299 console.log('no access');)
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3300 }
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3301 </example>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3302 </tag-desc>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3303
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3304 </list>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3305 </tag-desc>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3306
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
3307 <tag-name id="fs_appendfilesync"><literal>appendFileSync(<value>filename</value>,
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3308 <value>data</value>[, <value>options</value>])</literal></tag-name>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3309 <tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3310 Synchronously appends specified <literal>data</literal>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3311 to a file with provided <literal>filename</literal>.
2604
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3312 The <literal>data</literal> is expected to be a string
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3313 or a Buffer object (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3314 If the file does not exist, it will be created.
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3315 The <literal>options</literal> parameter is expected to be
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3316 an object with the following keys:
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3317 <list type="tag">
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3318
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3319 <tag-name><literal>mode</literal></tag-name>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3320 <tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3321 mode option, by default is <literal>0o666</literal>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3322 </tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3323
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3324 <tag-name><literal>flag</literal></tag-name>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3325 <tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3326 file system <link id="njs_api_fs_flags">flag</link>,
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3327 by default is <literal>a</literal>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3328 </tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3329
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3330 </list>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3331 </tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3332
2818
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3333 <tag-name id="fs_lstatsync"><literal>lstatSync(<value>path</value>[,
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3334 <value>options</value>])</literal></tag-name>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3335 <tag-desc>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3336 Synchronously retrieves
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3337 the <link id="fs_stats"><literal>fs.Stats</literal></link> object
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3338 for the symbolic link referred to by <literal>path</literal>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3339 (<link doc="changes.xml" id="njs0.7.1">0.7.1</link>).
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3340 The <literal>options</literal> parameter is expected to be
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3341 an object with the following keys:
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3342 <list type="tag">
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3343 <tag-name><literal>throwIfNoEntry</literal></tag-name>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3344 <tag-desc>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3345 a boolean value which indicates
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3346 whether an exception is thrown if no file system entry exists,
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3347 rather than returning <literal>undefined</literal>,
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3348 by default is <literal>false</literal>.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3349 </tag-desc>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3350 </list>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3351 </tag-desc>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3352
2563
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3353 <tag-name id="fs_mkdirsync"><literal>mkdirSync(<value>path</value>[,
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3354 <value>options</value>])</literal></tag-name>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3355 <tag-desc>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3356 Synchronously creates a directory at the specified <literal>path</literal>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3357 (<link doc="changes.xml" id="njs0.4.2">0.4.2</link>).
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3358 The <literal>options</literal> parameter is expected to be an
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3359 <literal>integer</literal> that specifies
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3360 the <link id="fs_mkdirsync_mode">mode</link>,
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3361 or an object with the following keys:
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3362 <list type="tag">
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3363
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3364 <tag-name id="fs_mkdirsync_mode"><literal>mode</literal></tag-name>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3365 <tag-desc>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3366 mode option, by default is <literal>0o777</literal>.
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3367 </tag-desc>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3368
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3369 </list>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3370 </tag-desc>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3371
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3372 <tag-name id="fs_readdirsync"><literal>readdirSync(<value>path</value>[,
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3373 <value>options</value>])</literal></tag-name>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3374 <tag-desc>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3375 Synchronously reads the contents of a directory
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3376 at the specified <literal>path</literal>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3377 (<link doc="changes.xml" id="njs0.4.2">0.4.2</link>).
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3378 The <literal>options</literal> parameter is expected to be
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3379 a string that specifies <link id="fs_readdirsync_encoding">encoding</link>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3380 or an object with the following keys:
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3381 <list type="tag">
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3382
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3383 <tag-name id="fs_readdirsync_encoding"><literal>encoding</literal></tag-name>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3384 <tag-desc>
2604
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3385 encoding, by default is <literal>utf8</literal>.
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3386 The encoding can be <literal>utf8</literal> and <literal>buffer</literal>
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3387 (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
2563
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3388 </tag-desc>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3389
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3390 <tag-name id="fs_readdirsync_withfiletypes"><literal>withFileTypes</literal></tag-name>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3391 <tag-desc>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3392 if set to <literal>true</literal>, the files array will contain
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3393 <link id="fs_dirent"><literal>fs.Dirent</literal></link> objects,
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3394 by default is <literal>false</literal>.
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3395 </tag-desc>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3396
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3397 </list>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3398 </tag-desc>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3399
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
3400 <tag-name id="fs_readfilesync"><literal>readFileSync(<value>filename</value>[,
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3401 <value>options</value>])</literal></tag-name>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3402 <tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3403 Synchronously returns the contents of the file
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3404 with provided <literal>filename</literal>.
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3405 The <literal>options</literal> parameter holds
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3406 <literal>string</literal> that specifies encoding.
2604
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3407 If an encoding is specified, a string is returned,
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3408 otherwise, a Buffer object
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3409 (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>) is returned.
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3410 <note>
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3411 Before version <link doc="changes.xml" id="njs0.4.4">0.4.4</link>,
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3412 a <link id="string_tobytes">byte string</link> was returned
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3413 if encoding was not specified.
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3414 </note>
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3415 Otherwise, <literal>options</literal> is expected to be
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3416 an object with the following keys:
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3417 <list type="tag">
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3418
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3419 <tag-name><literal>encoding</literal></tag-name>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3420 <tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3421 encoding, by default is not specified.
2604
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3422 The encoding can be <literal>utf8</literal>,
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3423 <literal>hex</literal>
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3424 (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3425 <literal>base64</literal>
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3426 (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>),
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3427 <literal>base64url</literal>
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3428 (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3429 </tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3430
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3431 <tag-name><literal>flag</literal></tag-name>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3432 <tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3433 file system <link id="njs_api_fs_flags">flag</link>,
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3434 by default is <literal>r</literal>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3435 </tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3436
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3437 </list>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3438 <example>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3439 >> var fs = require('fs')
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3440 undefined
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3441 >> var file = fs.readFileSync('/file/path.tar.gz')
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3442 undefined
2604
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3443 >> var gzipped = file.slice(0,2).toString('hex') === '1f8b'; gzipped
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3444 true
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3445 </example>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3446 </tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3447
2507
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3448 <tag-name id="fs_realpathsync"><literal>realpathSync(<value>path</value>[,
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3449 <value>options</value>])</literal></tag-name>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3450 <tag-desc>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3451 Synchronously computes the canonical pathname by resolving
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3452 <literal>.</literal>, <literal>..</literal> and symbolic links using
2508
d3d5b67a1462 Language fixes in njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2507
diff changeset
3453 <link url="http://man7.org/linux/man-pages/man3/realpath.3.html">realpath(3)</link>.
2507
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3454 The <literal>options</literal> argument can be a string specifying an encoding,
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3455 or an object with an encoding property specifying the character encoding
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3456 to use for the path passed to the callback
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3457 (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3458 </tag-desc>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3459
2509
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3460 <tag-name id="fs_renamesync"><literal>renameSync(<value>oldPath</value>,
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3461 <value>newPath</value>)</literal></tag-name>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3462 <tag-desc>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3463 Synchronously changes the name or location of a file from
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3464 <literal>oldPath</literal> to <literal>newPath</literal>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3465 (<link doc="changes.xml" id="njs0.3.4">0.3.4</link>).
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3466 <example>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3467 >> var fs = require('fs')
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3468 undefined
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3469 >> var file = fs.renameSync('hello.txt', 'HelloWorld.txt')
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3470 undefined
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3471 </example>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3472 </tag-desc>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3473
2563
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3474 <tag-name id="fs_rmdirsync"><literal>rmdirSync(<value>path</value>)</literal></tag-name>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3475 <tag-desc>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3476 Synchronously removes a directory at the specified <literal>path</literal>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3477 (<link doc="changes.xml" id="njs0.4.2">0.4.2</link>).
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3478 </tag-desc>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3479
2818
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3480 <tag-name id="fs_statsync"><literal>statSync(<value>path</value>,[
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3481 <value>options</value>])</literal></tag-name>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3482 <tag-desc>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3483 Synchronously retrieves
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3484 the <link id="fs_stats"><literal>fs.Stats</literal></link> object
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3485 for the specified <literal>path</literal>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3486 (<link doc="changes.xml" id="njs0.7.1">0.7.1</link>).
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3487 The <literal>path</literal> can be a
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3488 <literal>string</literal> or
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3489 <literal>buffer</literal>.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3490 The <literal>options</literal> parameter is expected to be
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3491 an object with the following keys:
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3492 <list type="tag">
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3493 <tag-name><literal>throwIfNoEntry</literal></tag-name>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3494 <tag-desc>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3495 a boolean value which indicates whether
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3496 an exception is thrown if no file system entry exists
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3497 rather than returning <literal>undefined</literal>,
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3498 by default is <literal>true</literal>.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3499 </tag-desc>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3500 </list>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3501 </tag-desc>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3502
2509
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3503 <tag-name id="fs_symlinksync"><literal>symlinkSync(<value>target</value>,
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3504 <value>path</value>)</literal></tag-name>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3505 <tag-desc>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3506 Synchronously creates the link called <literal>path</literal>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3507 pointing to <literal>target</literal> using
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3508 <link url="http://man7.org/linux/man-pages/man2/symlink.2.html">symlink(2)</link>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3509 (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3510 Relative targets are relative to the link’s parent directory.
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3511 </tag-desc>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3512
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3513 <tag-name id="fs_unlinksync"><literal>unlinkSync(<value>path</value>)</literal></tag-name>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3514 <tag-desc>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3515 Synchronously unlinks a file by <literal>path</literal>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3516 (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3517 </tag-desc>
827a6d7fe108 Reordered alphabetically njs file system methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2508
diff changeset
3518
2570
44792f1ee284 Added IDs to methods in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2569
diff changeset
3519 <tag-name id="fs_writefilesync"><literal>writeFileSync(<value>filename</value>,
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3520 <value>data</value>[,
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3521 <value>options</value>])</literal></tag-name>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3522 <tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3523 Synchronously writes <literal>data</literal> to a file
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3524 with provided <literal>filename</literal>.
2604
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3525 The <literal>data</literal> is expected to be a string
a29676472a11 Added Buffer object info to some njs methods.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2601
diff changeset
3526 or a Buffer object (<link doc="changes.xml" id="njs0.4.4">0.4.4</link>).
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3527 If the file does not exist, it will be created,
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3528 if the file exists, it will be replaced.
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3529 The <literal>options</literal> parameter is expected to be
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3530 an object with the following keys:
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3531 <list type="tag">
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3532 <tag-name><literal>mode</literal></tag-name>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3533 <tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3534 mode option, by default is <literal>0o666</literal>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3535 </tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3536
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3537 <tag-name><literal>flag</literal></tag-name>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3538 <tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3539 file system <link id="njs_api_fs_flags">flag</link>,
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3540 by default is <literal>w</literal>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3541 </tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3542
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3543 </list>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3544 <example>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3545 >> var fs = require('fs')
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3546 undefined
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3547 >> var file = fs.writeFileSync('hello.txt', 'Hello world')
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3548 undefined
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3549 </example>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3550 </tag-desc>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3551
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3552 </list>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3553 </para>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3554
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3555
2563
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3556 <section id="fs_dirent" name="fs.Dirent">
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3557
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3558 <para>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3559 <literal>fs.Dirent</literal> is a representation of a directory entry&mdash;
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3560 a file or a subdirectory.
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3561 When
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3562 <link id="fs_readdirsync"><literal>readdirSync()</literal></link>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3563 is called with the
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3564 <link id="fs_readdirsync_withfiletypes"><literal>withFileTypes</literal></link>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3565 option,
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3566 the resulting array contains <literal>fs.Dirent</literal> objects.
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3567
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3568 <list type= "bullet" compact="no">
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3569
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3570 <listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3571 <literal>dirent.isBlockDevice()</literal>&mdash;returns
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3572 <literal>true</literal> if the <literal>fs.Dirent</literal> object describes
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3573 a block device.
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3574 </listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3575
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3576 <listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3577 <literal>dirent.isCharacterDevice()</literal>&mdash;returns
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3578 <literal>true</literal> if the <literal>fs.Dirent</literal> object describes
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3579 a character device.
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3580 </listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3581
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3582 <listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3583 <literal>dirent.isDirectory()</literal>&mdash;returns
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3584 <literal>true</literal> if the <literal>fs.Dirent</literal> object describes
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3585 a file system directory.
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3586 </listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3587
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3588 <listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3589 <literal>dirent.isFIFO()</literal>&mdash;returns
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3590 <literal>true</literal> if the <literal>fs.Dirent</literal> object describes
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3591 a first-in-first-out (FIFO) pipe.
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3592 </listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3593
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3594 <listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3595 <literal>dirent.isFile()</literal>&mdash;returns
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3596 <literal>true</literal> if the <literal>fs.Dirent</literal> object describes
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3597 a regular file.
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3598 </listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3599
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3600 <listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3601 <literal>dirent.isSocket()</literal>&mdash;returns
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3602 <literal>true</literal> if the <literal>fs.Dirent</literal> object describes
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3603 a socket.
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3604 </listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3605
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3606 <listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3607 <literal>dirent.isSymbolicLink()</literal>&mdash;returns
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3608 <literal>true</literal> if the <literal>fs.Dirent</literal> object describes
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3609 a symbolic link.
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3610 </listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3611
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3612 <listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3613 <literal>dirent.name</literal>&mdash;
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3614 the name of the file <literal>fs.Dirent</literal> object refers to.
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3615 </listitem>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3616
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3617 </list>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3618 </para>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3619
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3620 </section>
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3621
428a8cf1911b Documented mkdirSync, readdirSync, rmdirSync, fs.Dirent in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2546
diff changeset
3622
2818
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3623 <section id="fs_stats" name="fs.Stats">
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3624
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3625 <para>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3626 The <literal>fs.Stats</literal> object provides information about a file.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3627 The object is returned from
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3628 <link id="fs_statsync">fs.statSync()</link> and
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3629 <link id="fs_lstatsync">fs.lstatSync()</link>.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3630
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3631 <list type= "bullet" compact="no">
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3632
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3633 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3634 <literal>stats.isBlockDevice()</literal>&mdash;returns
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3635 <literal>true</literal> if the <literal>fs.Stats</literal> object describes
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3636 a block device.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3637 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3638
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3639 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3640 <literal>stats.isDirectory()</literal>&mdash;returns
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3641 <literal>true</literal> if the <literal>fs.Stats</literal> object describes
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3642 a file system directory.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3643 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3644
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3645 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3646 <literal>stats.isFIFO()</literal>&mdash;returns
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3647 <literal>true</literal> if the <literal>fs.Stats</literal> object describes
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3648 a first-in-first-out (FIFO) pipe.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3649 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3650
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3651 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3652 <literal>stats.isFile()</literal>&mdash;returns
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3653 <literal>true</literal> if the <literal>fs.Stats</literal> object describes
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3654 a regular file.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3655 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3656
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3657 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3658 <literal>stats.isSocket()</literal>&mdash;returns
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3659 <literal>true</literal> if the <literal>fs.Stats</literal> object describes
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3660 a socket.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3661 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3662
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3663 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3664 <literal>stats.isSymbolicLink()</literal>&mdash;returns
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3665 <literal>true</literal> if the <literal>fs.Stats</literal> object describes
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3666 a symbolic link.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3667 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3668
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3669 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3670 <literal>stats.dev</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3671 the numeric identifier of the device containing the file.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3672 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3673
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3674 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3675 <literal>stats.ino</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3676 the file system specific <literal>Inode</literal> number for the file.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3677 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3678
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3679 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3680 <literal>stats.mode</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3681 a bit-field describing the file type and mode.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3682 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3683
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3684 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3685 <literal>stats.nlink</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3686 the number of hard-links that exist for the file.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3687 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3688
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3689 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3690 <literal>stats.uid</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3691 the numeric user identifier of the user that owns the file (POSIX).
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3692 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3693
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3694 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3695 <literal>stats.gid</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3696 the numeric group identifier of the group that owns the file (POSIX).
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3697 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3698
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3699 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3700 <literal>stats.rdev</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3701 the numeric device identifier if the file represents a device.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3702 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3703
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3704 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3705 <literal>stats.size</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3706 the size of the file in bytes.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3707 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3708
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3709 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3710 <literal>stats.blksize</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3711 the file system block size for i/o operations.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3712 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3713
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3714 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3715 <literal>stats.blocks</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3716 the number of blocks allocated for this file.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3717 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3718
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3719 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3720 <literal>stats.atimeMs</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3721 the timestamp indicating the last time this file was accessed expressed
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3722 in milliseconds since the POSIX Epoch.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3723 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3724
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3725 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3726 <literal>stats.mtimeMs</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3727 the timestamp indicating the last time this file was modified expressed
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3728 in milliseconds since the POSIX Epoch.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3729 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3730
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3731 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3732 <literal>stats.ctimeMs</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3733 the timestamp indicating the last time this file was changed expressed
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3734 in milliseconds since the POSIX Epoch.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3735 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3736
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3737 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3738 <literal>stats.birthtimeMs</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3739 the timestamp indicating the creation time of this file expressed
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3740 in milliseconds since the POSIX Epoch.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3741 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3742
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3743 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3744 <literal>stats.atime</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3745 the timestamp indicating the last time this file was accessed.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3746 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3747
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3748 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3749 <literal>stats.mtime</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3750 the timestamp indicating the last time this file was modified.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3751 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3752
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3753 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3754 <literal>stats.ctime</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3755 the timestamp indicating the last time this file was changed.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3756 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3757
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3758 <listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3759 <literal>stats.birthtime</literal>&mdash;
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3760 the timestamp indicating the creation time of this file.
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3761 </listitem>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3762
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3763 </list>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3764 </para>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3765
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3766 </section>
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3767
2594d336342d Documented fs.Stats, statSync and lstatSync in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2800
diff changeset
3768
2507
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3769 <section id="access_const" name="File Access Constants">
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3770
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3771 <para>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3772 The <link id="fs_accesssync"><literal>access()</literal></link> method
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3773 can accept the following flags.
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3774 These flags are exported by <literal>fs.constants</literal>:
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3775
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3776 <list type= "bullet" compact="no">
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3777
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3778 <listitem>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3779 <literal>F_OK</literal>&mdash;indicates that the file
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3780 is visible to the calling process,
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3781 used by default if no mode is specified
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3782 </listitem>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3783
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3784 <listitem>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3785 <literal>R_OK</literal>&mdash;indicates that the file can be
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3786 read by the calling process
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3787 </listitem>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3788
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3789 <listitem>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3790 <literal>W_OK</literal>&mdash;indicates that the file can be
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3791 written by the calling process
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3792 </listitem>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3793
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3794 <listitem>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3795 <literal>X_OK</literal>&mdash;indicates that the file can be
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3796 executed by the calling process
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3797 </listitem>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3798
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3799 </list>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3800 </para>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3801
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3802 </section>
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3803
8ad2ea80e0c2 njs-0.3.9
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2497
diff changeset
3804
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3805 <section id="njs_api_fs_flags" name="File System Flags">
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3806
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3807 <para>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3808 The <literal>flag</literal> option can accept the following values:
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3809
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3810 <list type= "bullet" compact="no">
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3811
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3812 <listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3813 <literal>a</literal>&mdash;open a file for appending.
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3814 The file is created if it does not exist
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3815 </listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3816
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3817 <listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3818 <literal>ax</literal>&mdash;the same as <literal>a</literal>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3819 but fails if the file already exists
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3820 </listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3821
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3822 <listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3823 <literal>a+</literal>&mdash;open a file for reading and appending.
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3824 If the file does not exist, it will be created
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3825 </listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3826
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3827 <listitem>
2579
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
3828 <literal>ax+</literal>&mdash;the same as <literal>a+</literal>
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3829 but fails if the file already exists
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3830 </listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3831
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3832 <listitem>
2579
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
3833 <literal>as</literal>&mdash;open a file for appending
63cef7604e0d Minor review of njs Reference for typos and style.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2578
diff changeset
3834 in synchronous mode.
2204
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3835 If the file does not exist, it will be created
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3836 </listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3837
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3838 <listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3839 <literal>as+</literal>&mdash;open a file for reading and appending
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3840 in synchronous mode.
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3841 If the file does not exist, it will be created
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3842 </listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3843
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3844 <listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3845 <literal>r</literal>&mdash;open a file for reading.
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3846 An exception occurs if the file does not exist
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3847 </listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3848
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3849 <listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3850 <literal>r+</literal>&mdash;open a file for reading and writing.
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3851 An exception occurs if the file does not exist
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3852 </listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3853
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3854 <listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3855 <literal>rs+</literal>&mdash;open a file for reading and writing
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3856 in synchronous mode.
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3857 Instructs the operating system to bypass the local file system cache
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3858 </listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3859
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3860 <listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3861 <literal>w</literal>&mdash;open a file for writing.
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3862 If the file does not exist, it will be created.
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3863 If the file exists, it will be replaced
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3864 </listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3865
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3866 <listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3867 <literal>wx</literal>&mdash;the same as <literal>w</literal>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3868 but fails if the file already exists
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3869 </listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3870
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3871 <listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3872 <literal>w+</literal>&mdash;open a file for reading and writing.
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3873 If the file does not exist, it will be created.
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3874 If the file exists, it will be replaced
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3875 </listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3876
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3877 <listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3878 <literal>wx+</literal>&mdash;the same as <literal>w+</literal>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3879 but fails if the file already exists
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3880 </listitem>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3881
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3882 </list>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3883 </para>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3884
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3885 </section>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3886
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3887 </section>
001f2d905fd9 Documented fileSystem methods in njs.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2203
diff changeset
3888
2583
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3889
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3890 <section id="querystring" name="Query String">
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3891
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3892 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3893 The Query String module provides support
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3894 for parsing and formatting URL query strings
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3895 (<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3896 The Query String module object is returned by
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3897 <literal>require('querystring')</literal>.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3898 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3899
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3900 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3901 <list type="tag">
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3902
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3903 <tag-name id="querystring_decode"><literal>querystring.decode()</literal></tag-name>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3904 <tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3905 is an alias for
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3906 <link id="querystring_parse"><literal>querystring.parse()</literal></link>.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3907 </tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3908
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3909 <tag-name id="querystring_encode"><literal>querystring.encode()</literal></tag-name>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3910 <tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3911 is an alias for
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3912 <link id="querystring_stringify"><literal>querystring.stringify()</literal></link>.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3913 </tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3914
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3915 <tag-name id="querystring_escape"><literal>querystring.escape(<value>string</value>)</literal></tag-name>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3916 <tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3917 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3918 Performs URL encoding of the given <literal>string</literal>,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3919 returns an escaped query string.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3920 The method is used by
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3921 <link id="querystring_stringify"><literal>querystring.stringify()</literal></link>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3922 and should not be used directly.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3923 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3924 </tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3925
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3926 <tag-name id="querystring_parse"><literal>querystring.parse(<value>string</value>[,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3927 <value>separator</value>[,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3928 <value>equal</value>[,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3929 <value>options</value>]]])</literal></tag-name>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3930 <tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3931 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3932 Parses the query string URL and returns an object.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3933 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3934
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3935 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3936 The <literal>separator</literal> parameter is a substring
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3937 for delimiting key and value pairs in the query string,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3938 by default is “<literal>&amp;</literal>”.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3939 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3940
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3941 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3942 The <literal>equal</literal> parameter is a substring
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3943 for delimiting keys and values in the query string,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3944 by default is “<literal>=</literal>”.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3945 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3946
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3947 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3948 The <literal>options</literal> parameter is expected to be
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3949 an object with the following keys:
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3950 <list type="tag">
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3951 <tag-name><literal>decodeURIComponent</literal>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3952 <value>function</value></tag-name>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3953 <tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3954 Function used
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3955 to decode percent-encoded characters in the query string,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3956 by default is
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3957 <link id="querystring_unescape"><literal>querystring.unescape()</literal></link>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3958 </tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3959
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3960 <tag-name><literal>maxKeys</literal>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3961 <value>number</value></tag-name>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3962 <tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3963 the maximum number of keys to parse,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3964 by default is <literal>1000</literal>.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3965 The <literal>0</literal> value removes limitations for counting keys.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3966 </tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3967
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3968 </list>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3969 By default, percent-encoded characters within the query string are assumed
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3970 to use the UTF-8 encoding,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3971 invalid UTF-8 sequences will be replaced with
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3972 the <literal>U+FFFD</literal> replacement character.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3973 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3974
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3975 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3976 For example, for the following query string
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3977 <example>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3978 'foo=bar&amp;abc=xyz&amp;abc=123'
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3979 </example>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3980 the output will be:
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3981 <example>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3982 {
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3983 foo: 'bar',
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3984 abc: ['xyz', '123']
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3985 }
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3986 </example>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3987 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3988
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3989 </tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3990
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3991 <tag-name id="querystring_stringify"><literal>querystring.stringify(<value>object</value>[,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3992 <value>separator</value>[,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3993 <value>equal</value>[,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3994 <value>options</value>]]])</literal></tag-name>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3995 <tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3996 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3997 Serializes an object and returns a URL query string.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3998 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
3999
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4000 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4001 The <literal>separator</literal> parameter is a substring
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4002 for delimiting key and value pairs in the query string,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4003 by default is “<literal>&amp;</literal>”.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4004 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4005
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4006 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4007 The <literal>equal</literal> parameter is a substring
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4008 for delimiting keys and values in the query string,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4009 by default is “<literal>=</literal>”.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4010 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4011
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4012 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4013 The <literal>options</literal> parameter is expected to be
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4014 an object with the following keys:
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4015 <list type="tag">
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4016 <tag-name><literal>encodeURIComponent</literal>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4017 <value>function</value></tag-name>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4018 <tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4019 The function to use when converting
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4020 URL-unsafe characters to percent-encoding in the query string,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4021 by default is
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4022 <link id="querystring_escape"><literal>querystring.escape()</literal></link>.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4023 </tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4024
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4025 </list>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4026 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4027
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4028 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4029 By default, characters that require percent-encoding within the query string
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4030 are encoded as UTF-8.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4031 If other encoding is required, then
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4032 <literal>encodeURIComponent</literal> option should be specified.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4033 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4034
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4035 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4036 For example, for the following command
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4037 <example>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4038 querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], 123: '' });
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4039 </example>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4040 the query string will be:
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4041 <example>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4042 'foo=bar&amp;baz=qux&amp;baz=quux&amp;123='
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4043 </example>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4044 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4045
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4046 </tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4047
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4048 <tag-name id="querystring_unescape"><literal>querystring.unescape(<value>string</value>)</literal></tag-name>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4049 <tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4050 <para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4051 Performs decoding of URL percent-encoded characters
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4052 of the <literal>string</literal>,
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4053 returns an unescaped query string.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4054 The method is used by
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4055 <link id="querystring_parse"><literal>querystring.parse()</literal></link>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4056 and should not be used directly.
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4057 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4058 </tag-desc>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4059
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4060 </list>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4061 </para>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4062
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4063 </section>
cd97adddd757 Documented Query String in njs Reference.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2582
diff changeset
4064
2176
95b406f1f347 Added njs JSON API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2175
diff changeset
4065 </section>
95b406f1f347 Added njs JSON API.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2175
diff changeset
4066
2175
cd4889fdcfa4 Moved njs HTTP and Stream API to a separate page.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
4067 </article>