Mercurial > hg > nginx-site

comparison xml/en/docs/njs/reference.xml @ 2570:44792f1ee284

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added IDs to methods in njs Reference.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 16 Jul 2020 08:22:37 +0100
parents 2edc64c05b0e
children 3e47eecce384
comparison
equal deleted inserted replaced
2569:2edc64c05b0e 2570:44792f1ee284
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> 7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
8 8
9 <article name="Reference" 9 <article name="Reference"
10 link="/en/docs/njs/reference.html" 10 link="/en/docs/njs/reference.html"
11 lang="en" 11 lang="en"
12 rev="46"> 12 rev="47">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 <link doc="index.xml">njs</link> provides objects, methods and properties 17 <link doc="index.xml">njs</link> provides objects, methods and properties
38 <section id="http" name="HTTP Request"> 38 <section id="http" name="HTTP Request">
39 39
40 <para> 40 <para>
41 The HTTP request object is available only in the 41 The HTTP request object is available only in the
42 <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> module. 42 <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> module.
43 All string properties of the object are <link id="string">byte strings</link>. 43 All string properties of the object are
44 <link id="string">byte strings</link>.
44 45
45 <list type="tag"> 46 <list type="tag">
46 47
47 <tag-name id="r_args"><literal>r.args{}</literal></tag-name> 48 <tag-name id="r_args"><literal>r.args{}</literal></tag-name>
48 <tag-desc> 49 <tag-desc>
49 request arguments object, read-only 50 request arguments object, read-only
50 </tag-desc> 51 </tag-desc>
51 52
52 <tag-name><literal>r.error(<value>string</value>)</literal></tag-name> 53 <tag-name id="r_error"><literal>r.error(<value>string</value>)</literal></tag-name>
53 <tag-desc> 54 <tag-desc>
54 writes a <literal>string</literal> to the error log 55 writes a <literal>string</literal> to the error log
55 on the <literal>error</literal> level of logging 56 on the <literal>error</literal> level of logging
56 </tag-desc> 57 </tag-desc>
57 58
58 <tag-name><literal>r.finish()</literal></tag-name> 59 <tag-name id="r_finish"><literal>r.finish()</literal></tag-name>
59 <tag-desc> 60 <tag-desc>
60 finishes sending a response to the client 61 finishes sending a response to the client
61 </tag-desc> 62 </tag-desc>
62 63
63 <tag-name id="r_headers_in"><literal>r.headersIn{}</literal></tag-name> 64 <tag-name id="r_headers_in"><literal>r.headersIn{}</literal></tag-name>
143 Duplicate field values in all other response headers 144 Duplicate field values in all other response headers
144 are separated by commas. 145 are separated by commas.
145 </para> 146 </para>
146 </tag-desc> 147 </tag-desc>
147 148
148 <tag-name><literal>r.httpVersion</literal></tag-name> 149 <tag-name id="r_http_version"><literal>r.httpVersion</literal></tag-name>
149 <tag-desc> 150 <tag-desc>
150 HTTP version, read-only 151 HTTP version, read-only
151 </tag-desc> 152 </tag-desc>
152 153
153 <tag-name id="r_internal_redirect"><literal>r.internalRedirect(<value>uri</value>)</literal></tag-name> 154 <tag-name id="r_internal_redirect"><literal>r.internalRedirect(<value>uri</value>)</literal></tag-name>
156 If the uri starts with the “<literal>@</literal>” prefix, 157 If the uri starts with the “<literal>@</literal>” prefix,
157 it is considered a named location. 158 it is considered a named location.
158 The actual redirect happens after the handler execution is completed. 159 The actual redirect happens after the handler execution is completed.
159 </tag-desc> 160 </tag-desc>
160 161
161 <tag-name><literal>r.log(<value>string</value>)</literal></tag-name> 162 <tag-name id="r_log"><literal>r.log(<value>string</value>)</literal></tag-name>
162 <tag-desc> 163 <tag-desc>
163 writes a <literal>string</literal> to the error log 164 writes a <literal>string</literal> to the error log
164 on the <literal>info</literal> level of logging 165 on the <literal>info</literal> level of logging
165 </tag-desc> 166 </tag-desc>
166 167
167 <tag-name><literal>r.method</literal></tag-name> 168 <tag-name id="r_method"><literal>r.method</literal></tag-name>
168 <tag-desc> 169 <tag-desc>
169 HTTP method, read-only 170 HTTP method, read-only
170 </tag-desc> 171 </tag-desc>
171 172
172 <tag-name id="r_parent"><literal>r.parent</literal></tag-name> 173 <tag-name id="r_parent"><literal>r.parent</literal></tag-name>
173 <tag-desc> 174 <tag-desc>
174 references the parent request object 175 references the parent request object
175 </tag-desc> 176 </tag-desc>
176 177
177 <tag-name><literal>r.remoteAddress</literal></tag-name> 178 <tag-name id="r_remote_address"><literal>r.remoteAddress</literal></tag-name>
178 <tag-desc> 179 <tag-desc>
179 client address, read-only 180 client address, read-only
180 </tag-desc> 181 </tag-desc>
181 182
182 <tag-name id="r_raw_headers_in"><literal>r.rawHeadersIn{}</literal></tag-name> 183 <tag-name id="r_raw_headers_in"><literal>r.rawHeadersIn{}</literal></tag-name>
234 <link doc="../http/ngx_http_js_module.xml" id="js_content"/> directive. 235 <link doc="../http/ngx_http_js_module.xml" id="js_content"/> directive.
235 </tag-desc> 236 </tag-desc>
236 237
237 <tag-name id="r_response_body"><literal>r.responseBody</literal></tag-name> 238 <tag-name id="r_response_body"><literal>r.responseBody</literal></tag-name>
238 <tag-desc> 239 <tag-desc>
239 holds the <link id="subrequest">subrequest</link> response body, read-only. 240 holds the <link id="r_subrequest">subrequest</link> response body, read-only.
240 The size of <literal>r.responseBody</literal> is limited by the 241 The size of <literal>r.responseBody</literal> is limited by the
241 <link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/> 242 <link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/>
242 directive. 243 directive.
243 </tag-desc> 244 </tag-desc>
244 245
245 <tag-name><literal>r.return(status[, string])</literal></tag-name> 246 <tag-name id="r_return"><literal>r.return(status[, string])</literal></tag-name>
246 <tag-desc> 247 <tag-desc>
247 sends the entire response 248 sends the entire response
248 with the specified <literal>status</literal> to the client 249 with the specified <literal>status</literal> to the client
249 <para> 250 <para>
250 It is possible to specify either a redirect URL 251 It is possible to specify either a redirect URL
251 (for codes 301, 302, 303, 307, and 308) 252 (for codes 301, 302, 303, 307, and 308)
252 or the response body text (for other codes) as the second argument 253 or the response body text (for other codes) as the second argument
253 </para> 254 </para>
254 </tag-desc> 255 </tag-desc>
255 256
256 <tag-name><literal>r.send(<value>string</value>)</literal></tag-name> 257 <tag-name id="r_send"><literal>r.send(<value>string</value>)</literal></tag-name>
257 <tag-desc> 258 <tag-desc>
258 sends a part of the response body to the client 259 sends a part of the response body to the client
259 </tag-desc> 260 </tag-desc>
260 261
261 <tag-name><literal>r.sendHeader()</literal></tag-name> 262 <tag-name><literal>r.sendHeader()</literal></tag-name>
262 <tag-desc> 263 <tag-desc>
263 sends the HTTP headers to the client 264 sends the HTTP headers to the client
264 </tag-desc> 265 </tag-desc>
265 266
266 <tag-name><literal>r.status</literal></tag-name> 267 <tag-name id="r_status"><literal>r.status</literal></tag-name>
267 <tag-desc> 268 <tag-desc>
268 status, writable 269 status, writable
269 </tag-desc> 270 </tag-desc>
270 271
271 <tag-name id="subrequest"><literal>r.subrequest(<value>uri</value>[, 272 <tag-name id="r_subrequest"><literal>r.subrequest(<value>uri</value>[,
272 <value>options</value>[, <value>callback</value>]])</literal></tag-name> 273 <value>options</value>[, <value>callback</value>]])</literal></tag-name>
273 <tag-desc> 274 <tag-desc>
274 creates a subrequest with the given <literal>uri</literal> and 275 creates a subrequest with the given <literal>uri</literal> and
275 <literal>options</literal>, and installs 276 <literal>options</literal>, and installs
276 an optional completion <literal>callback</literal>. 277 an optional completion <literal>callback</literal>.
347 <tag-desc> 348 <tag-desc>
348 nginx variables object, 349 nginx variables object,
349 writable (since <link doc="changes.xml" id="njs0.2.8">0.2.8</link>) 350 writable (since <link doc="changes.xml" id="njs0.2.8">0.2.8</link>)
350 </tag-desc> 351 </tag-desc>
351 352
352 <tag-name><literal>r.warn(<value>string</value>)</literal></tag-name> 353 <tag-name id="r_warn"><literal>r.warn(<value>string</value>)</literal></tag-name>
353 <tag-desc> 354 <tag-desc>
354 writes a <literal>string</literal> to the error log 355 writes a <literal>string</literal> to the error log
355 on the <literal>warning</literal> level of logging 356 on the <literal>warning</literal> level of logging
356 </tag-desc> 357 </tag-desc>
357 358
396 successfully finalizes the current phase handler 397 successfully finalizes the current phase handler
397 or finalizes it with the specified numeric code 398 or finalizes it with the specified numeric code
398 (<link doc="changes.xml" id="njs0.2.4">0.2.4</link>). 399 (<link doc="changes.xml" id="njs0.2.4">0.2.4</link>).
399 </tag-desc> 400 </tag-desc>
400 401
401 <tag-name><literal>s.error(<value>string</value>)</literal></tag-name> 402 <tag-name id="s_error"><literal>s.error(<value>string</value>)</literal></tag-name>
402 <tag-desc> 403 <tag-desc>
403 writes a sent <literal>string</literal> to the error log 404 writes a sent <literal>string</literal> to the error log
404 on the <literal>error</literal> level of logging 405 on the <literal>error</literal> level of logging
405 </tag-desc> 406 </tag-desc>
406 407
407 <tag-name><literal>s.log(<value>string</value>)</literal></tag-name> 408 <tag-name id="s_log"><literal>s.log(<value>string</value>)</literal></tag-name>
408 <tag-desc> 409 <tag-desc>
409 writes a sent <value>string</value> to the error log 410 writes a sent <value>string</value> to the error log
410 on the <literal>info</literal> level of logging 411 on the <literal>info</literal> level of logging
411 </tag-desc> 412 </tag-desc>
412 413
452 453
453 </list> 454 </list>
454 </para> 455 </para>
455 </tag-desc> 456 </tag-desc>
456 457
457 <tag-name><literal>s.remoteAddress</literal></tag-name> 458 <tag-name id="s_remote_address"><literal>s.remoteAddress</literal></tag-name>
458 <tag-desc> 459 <tag-desc>
459 client address, read-only 460 client address, read-only
460 </tag-desc> 461 </tag-desc>
461 462
462 <tag-name id="s_send"><literal>s.send(<value>data</value>[, 463 <tag-name id="s_send"><literal>s.send(<value>data</value>[,
488 <tag-desc> 489 <tag-desc>
489 nginx variables object, writable 490 nginx variables object, writable
490 (since <link doc="changes.xml" id="njs0.2.8">0.2.8</link>) 491 (since <link doc="changes.xml" id="njs0.2.8">0.2.8</link>)
491 </tag-desc> 492 </tag-desc>
492 493
493 <tag-name><literal>s.warn(<value>string</value>)</literal></tag-name> 494 <tag-name id="s_warn"><literal>s.warn(<value>string</value>)</literal></tag-name>
494 <tag-desc> 495 <tag-desc>
495 writes a sent <literal>string</literal> to the error log 496 writes a sent <literal>string</literal> to the error log
496 on the <literal>warning</literal> level of logging 497 on the <literal>warning</literal> level of logging
497 </tag-desc> 498 </tag-desc>
498 499
643 Serializes a Unicode string to a byte string. 644 Serializes a Unicode string to a byte string.
644 Returns <literal>null</literal> if a character larger than 255 is 645 Returns <literal>null</literal> if a character larger than 255 is
645 found in the string. 646 found in the string.
646 </tag-desc> 647 </tag-desc>
647 648
648 <tag-name><literal>String.prototype.toString([<value>encoding</value>])</literal></tag-name> 649 <tag-name id="string_tostring"><literal>String.prototype.toString([<value>encoding</value>])</literal></tag-name>
649 <tag-desc> 650 <tag-desc>
650 <para> 651 <para>
651 If no <literal>encoding</literal> is specified, 652 If no <literal>encoding</literal> is specified,
652 returns a specified Unicode string or byte string as in ECMAScript. 653 returns a specified Unicode string or byte string as in ECMAScript.
653 </para> 654 </para>
879 </tag-desc> 880 </tag-desc>
880 881
881 </list> 882 </list>
882 </tag-desc> 883 </tag-desc>
883 884
884 <tag-name id="appendfilesync"><literal>appendFileSync(<value>filename</value>, 885 <tag-name id="fs_appendfilesync"><literal>appendFileSync(<value>filename</value>,
885 <value>data</value>[, <value>options</value>])</literal></tag-name> 886 <value>data</value>[, <value>options</value>])</literal></tag-name>
886 <tag-desc> 887 <tag-desc>
887 Synchronously appends specified <literal>data</literal> 888 Synchronously appends specified <literal>data</literal>
888 to a file with provided <literal>filename</literal>. 889 to a file with provided <literal>filename</literal>.
889 If the file does not exist, it will be created. 890 If the file does not exist, it will be created.
949 </tag-desc> 950 </tag-desc>
950 951
951 </list> 952 </list>
952 </tag-desc> 953 </tag-desc>
953 954
954 <tag-name id="readfilesync"><literal>readFileSync(<value>filename</value>[, 955 <tag-name id="fs_readfilesync"><literal>readFileSync(<value>filename</value>[,
955 <value>options</value>])</literal></tag-name> 956 <value>options</value>])</literal></tag-name>
956 <tag-desc> 957 <tag-desc>
957 Synchronously returns the contents of the file 958 Synchronously returns the contents of the file
958 with provided <literal>filename</literal>. 959 with provided <literal>filename</literal>.
959 The <literal>options</literal> parameter holds 960 The <literal>options</literal> parameter holds
1033 <tag-desc> 1034 <tag-desc>
1034 Synchronously unlinks a file by <literal>path</literal> 1035 Synchronously unlinks a file by <literal>path</literal>
1035 (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>). 1036 (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
1036 </tag-desc> 1037 </tag-desc>
1037 1038
1038 <tag-name id="writefilesync"><literal>writeFileSync(<value>filename</value>, 1039 <tag-name id="fs_writefilesync"><literal>writeFileSync(<value>filename</value>,
1039 <value>data</value>[, 1040 <value>data</value>[,
1040 <value>options</value>])</literal></tag-name> 1041 <value>options</value>])</literal></tag-name>
1041 <tag-desc> 1042 <tag-desc>
1042 Synchronously writes <literal>data</literal> to a file 1043 Synchronously writes <literal>data</literal> to a file
1043 with provided <literal>filename</literal>. 1044 with provided <literal>filename</literal>.