Mercurial > hg > nginx-site

comparison xml/en/docs/dev/development_guide.xml @ 1993:98b713b0a9fa

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Language and style fixes in development guide.
author Roman Arutyunyan <arut@nginx.com>
date Tue, 30 May 2017 14:30:04 +0300
parents 7660d6390a9d
children effdf0747a05
comparison
equal deleted inserted replaced
1992:e92780d00a6d 1993:98b713b0a9fa
14 <section name="Introduction" id="introduction"> 14 <section name="Introduction" id="introduction">
15 15
16 16
17 <section name="Code layout" id="code_layout"> 17 <section name="Code layout" id="code_layout">
18 18
19 <para>
20 <list type="bullet"> 19 <list type="bullet">
21 <listitem> 20 <listitem>
22 <literal>auto</literal> — build scripts 21 <literal>auto</literal> — Build scripts
23 </listitem> 22 </listitem>
24 23
25 <listitem> 24 <listitem>
26 <literal>src</literal> 25 <literal>src</literal>
27 26
28 <list type="bullet"> 27 <list type="bullet">
29 28
30 <listitem> 29 <listitem>
31 <literal>core</literal> — basic types and functions — string, array, log, 30 <literal>core</literal> — Basic types and functions — string, array, log,
32 pool etc 31 pool, etc.
33 </listitem> 32 </listitem>
34 33
35 <listitem> 34 <listitem>
36 <literal>event</literal> — event core 35 <literal>event</literal> — Event core
37 36
38 <list type="bullet"> 37 <list type="bullet">
39 38
40 <listitem> 39 <listitem>
41 <literal>modules</literal> — event notification modules: epoll, kqueue, 40 <literal>modules</literal> — Event notification modules:
42 select etc 41 <literal>epoll</literal>, <literal>kqueue</literal>, <literal>select</literal>
42 etc.
43 </listitem> 43 </listitem>
44 44
45 </list> 45 </list>
46 46
47 </listitem> 47 </listitem>
48 48
49 <listitem> 49 <listitem>
50 <literal>http</literal> — core HTTP module and common code 50 <literal>http</literal> — Core HTTP module and common code
51 51
52 <list type="bullet"> 52 <list type="bullet">
53 53
54 <listitem> 54 <listitem>
55 <literal>modules</literal> — other HTTP modules 55 <literal>modules</literal> — Other HTTP modules
56 </listitem> 56 </listitem>
57 57
58 <listitem> 58 <listitem>
59 <literal>v2</literal> — HTTPv2 59 <literal>v2</literal> — HTTP/2
60 </listitem> 60 </listitem>
61 61
62 </list> 62 </list>
63 63
64 </listitem> 64 </listitem>
65 65
66 <listitem> 66 <listitem>
67 <literal>mail</literal> — mail modules 67 <literal>mail</literal> — Mail modules
68 </listitem> 68 </listitem>
69 69
70 <listitem> 70 <listitem>
71 <literal>os</literal> — platform-specific code 71 <literal>os</literal> — Platform-specific code
72 72
73 <list type="bullet"> 73 <list type="bullet">
74 74
75 <listitem> 75 <listitem>
76 <literal>unix</literal> 76 <literal>unix</literal>
83 </list> 83 </list>
84 84
85 </listitem> 85 </listitem>
86 86
87 <listitem> 87 <listitem>
88 <literal>stream</literal> — stream modules 88 <literal>stream</literal> — Stream modules
89 </listitem> 89 </listitem>
90 90
91 </list> 91 </list>
92 92
93 </listitem> 93 </listitem>
94 94
95 </list> 95 </list>
96 </para>
97 96
98 </section> 97 </section>
99 98
100 99
101 <section name="Include files" id="include_files"> 100 <section name="Include files" id="include_files">
102 101
103 <para> 102 <para>
104 Each nginx file should start with including the following two files: 103 The following two <literal>#include</literal> statements must appear at the
105 </para> 104 beginning of every nginx file:
106 105 </para>
107 106
108 <programlisting> 107 <programlisting>
109 #include &lt;ngx_config.h> 108 #include &lt;ngx_config.h>
110 #include &lt;ngx_core.h> 109 #include &lt;ngx_core.h>
111 </programlisting> 110 </programlisting>
141 140
142 141
143 <section name="Integers" id="integers"> 142 <section name="Integers" id="integers">
144 143
145 <para> 144 <para>
146 For general purpose, nginx code uses the following two integer types 145 For general purposes, nginx code uses two integer types,
147 <literal>ngx_int_t</literal> and <literal>ngx_uint_t</literal> which are 146 <literal>ngx_int_t</literal> and <literal>ngx_uint_t</literal>, which are
148 typedefs for <literal>intptr_t</literal> and <literal>uintptr_t</literal>. 147 typedefs for <literal>intptr_t</literal> and <literal>uintptr_t</literal>
148 respectively.
149 </para> 149 </para>
150 150
151 </section> 151 </section>
152 152
153 153
155 155
156 <para> 156 <para>
157 Most functions in nginx return the following codes: 157 Most functions in nginx return the following codes:
158 </para> 158 </para>
159 159
160 <para>
161 <list type="bullet"> 160 <list type="bullet">
162 161
163 <listitem> 162 <listitem>
164 <literal>NGX_OK</literal> — operation succeeded 163 <literal>NGX_OK</literal> — Operation succeeded.
165 </listitem> 164 </listitem>
166 165
167 <listitem> 166 <listitem>
168 <literal>NGX_ERROR</literal> — operation failed 167 <literal>NGX_ERROR</literal> — Operation failed.
169 </listitem> 168 </listitem>
170 169
171 <listitem> 170 <listitem>
172 <literal>NGX_AGAIN</literal> — operation incomplete, function should be called 171 <literal>NGX_AGAIN</literal> — Operation incomplete; call the function again.
173 again 172 </listitem>
174 </listitem> 173
175 174 <listitem>
176 <listitem> 175 <literal>NGX_DECLINED</literal> — Operation rejected, for example, because it is
177 <literal>NGX_DECLINED</literal> — operation rejected, for example, if disabled 176 disabled in the configuration. This is never an error.
178 in configuration. This is never an error 177 </listitem>
179 </listitem> 178
180 179 <listitem>
181 <listitem> 180 <literal>NGX_BUSY</literal> — Resource is not available.
182 <literal>NGX_BUSY</literal> — resource is not available 181 </listitem>
183 </listitem> 182
184 183 <listitem>
185 <listitem> 184 <literal>NGX_DONE</literal> — Operation complete or continued elsewhere.
186 <literal>NGX_DONE</literal> — operation done or continued elsewhere. 185 Also used as an alternative success code.
187 Also used as an alternative success code 186 </listitem>
188 </listitem> 187
189 188 <listitem>
190 <listitem> 189 <literal>NGX_ABORT</literal> — Function was aborted.
191 <literal>NGX_ABORT</literal> — function was aborted. 190 Also used as an alternative error code.
192 Also used as an alternative error code
193 </listitem> 191 </listitem>
194 192
195 </list> 193 </list>
196 </para>
197 194
198 </section> 195 </section>
199 196
200 197
201 <section name="Error handling" id="error_handling"> 198 <section name="Error handling" id="error_handling">
202 199
203 <para> 200 <para>
204 For getting the last system error code, the <literal>ngx_errno</literal> macro 201 The <literal>ngx_errno</literal> macro returns the last system error code.
205 is available.
206 It's mapped to <literal>errno</literal> on POSIX platforms and to 202 It's mapped to <literal>errno</literal> on POSIX platforms and to
207 <literal>GetLastError()</literal> call in Windows. 203 <literal>GetLastError()</literal> call in Windows.
208 For getting the last socket error number, the 204 The <literal>ngx_socket_errno</literal> macro returns the last socket error
209 <literal>ngx_socket_errno</literal> macro is available. 205 number.
210 It's mapped to <literal>errno</literal> on POSIX systems as well, 206 Like the <literal>ngx_errno</literal> macro, it's mapped to
211 and to <literal>WSAGetLastError()</literal> call on Windows. 207 <literal>errno</literal> on POSIX platforms.
212 For performance reasons the values of <literal>ngx_errno</literal> or 208 It's mapped to the <literal>WSAGetLastError()</literal> call on Windows.
213 <literal>ngx_socket_errno</literal> should not be accessed more than 209 Accessing the values of <literal>ngx_errno</literal> or
214 once in a row. 210 <literal>ngx_socket_errno</literal> more than once in a row can cause
215 The error value should be stored in a local variable of type 211 performance issues.
216 <literal>ngx_err_t</literal> for using multiple times, if required. 212 If the error value might be used multiple times, store it in a local variable
217 For setting errors, <literal>ngx_set_errno(errno)</literal> and 213 of type <literal>ngx_err_t</literal>.
218 <literal>ngx_set_socket_errno(errno)</literal> macros are available. 214 To set errors, use the <literal>ngx_set_errno(errno)</literal> and
219 </para> 215 <literal>ngx_set_socket_errno(errno)</literal> macros.
220 216 </para>
221 <para> 217
222 The values of <literal>ngx_errno</literal> or 218 <para>
223 <literal>ngx_socket_errno</literal> can be passed to logging functions 219 The values of <literal>ngx_errno</literal> and
220 <literal>ngx_socket_errno</literal> can be passed to the logging functions
224 <literal>ngx_log_error()</literal> and <literal>ngx_log_debugX()</literal>, in 221 <literal>ngx_log_error()</literal> and <literal>ngx_log_debugX()</literal>, in
225 which case system error text is added to the log message. 222 which case system error text is added to the log message.
226 </para> 223 </para>
227 224
228 <para> 225 <para>
262 259
263 260
264 <section name="Overview" id="overview"> 261 <section name="Overview" id="overview">
265 262
266 <para> 263 <para>
267 For C strings, nginx code uses unsigned character type pointer 264 For C strings, nginx uses the unsigned character type pointer
268 <literal>u_char *</literal>. 265 <literal>u_char *</literal>.
269 </para> 266 </para>
270 267
271 <para> 268 <para>
272 The nginx string type <literal>ngx_str_t</literal> is defined as follows: 269 The nginx string type <literal>ngx_str_t</literal> is defined as follows:
279 u_char *data; 276 u_char *data;
280 } ngx_str_t; 277 } ngx_str_t;
281 </programlisting> 278 </programlisting>
282 279
283 <para> 280 <para>
284 The <literal>len</literal> field holds the string length, 281 The <literal>len</literal> field holds the string length and
285 <literal>data</literal> holds the string data. 282 <literal>data</literal> holds the string data.
286 The string, held in <literal>ngx_str_t</literal>, may or may not be 283 The string, held in <literal>ngx_str_t</literal>, may or may not be
287 null-terminated after the <literal>len</literal> bytes. 284 null-terminated after the <literal>len</literal> bytes.
288 In most cases it’s not. 285 In most cases it’s not.
289 However, in certain parts of code (for example, when parsing configuration), 286 However, in certain parts of the code (for example, when parsing configuration),
290 <literal>ngx_str_t</literal> objects are known to be null-terminated, and that 287 <literal>ngx_str_t</literal> objects are known to be null-terminated, which
291 knowledge is used to simplify string comparison and makes it easier to pass 288 simplifies string comparison and makes it easier to pass the strings to
292 those strings to syscalls. 289 syscalls.
293 </para> 290 </para>
294 291
295 <para> 292 <para>
296 A number of string operations are provided in nginx. 293 The string operations in nginx are declared in
297 They are declared in <path>src/core/ngx_string.h</path>. 294 <path>src/core/ngx_string.h</path>
298 Some of them are wrappers around standard C functions: 295 Some of them are wrappers around standard C functions:
299 </para> 296 </para>
300 297
301 <para> 298 <para>
302 <list type="bullet"> 299 <list type="bullet">
340 </list> 337 </list>
341 338
342 </para> 339 </para>
343 340
344 <para> 341 <para>
345 Some nginx-specific string functions: 342 Other string functions are nginx-specific
346 </para> 343 </para>
347 344
348 <para> 345 <para>
349 <list type="bullet"> 346 <list type="bullet">
350 347
351 <listitem> 348 <listitem>
352 <literal>ngx_memzero()</literal> fills memory with zeroes 349 <literal>ngx_memzero()</literal> — Fills memory with zeroes.
353 </listitem> 350 </listitem>
354 351
355 <listitem> 352 <listitem>
356 <literal>ngx_cpymem()</literal> does the same as 353 <literal>ngx_cpymem()</literal> — Does the same as
357 <literal>ngx_memcpy()</literal>, but returns the final destination address 354 <literal>ngx_memcpy()</literal>, but returns the final destination address
358 This one is handy for appending multiple strings in a row 355 This one is handy for appending multiple strings in a row.
359 </listitem> 356 </listitem>
360 357
361 <listitem> 358 <listitem>
362 <literal>ngx_movemem()</literal> does the same as 359 <literal>ngx_movemem()</literal> — Does the same as
363 <literal>ngx_memmove()</literal>, but returns the final destination address. 360 <literal>ngx_memmove()</literal>, but returns the final destination address.
364 </listitem> 361 </listitem>
365 362
366 <listitem> 363 <listitem>
367 <literal>ngx_strlchr()</literal> searches for a character in a string, 364 <literal>ngx_strlchr()</literal> — Searches for a character in a string,
368 delimited by two pointers 365 delimited by two pointers.
369 </listitem> 366 </listitem>
370 </list> 367 </list>
371 </para> 368 </para>
372 369
373 <para> 370 <para>
374 Some case conversion and comparison functions: 371 The following functions perform case conversion and comparison:
375 </para> 372 </para>
376 373
377 <para> 374 <para>
378 <list type="bullet"> 375 <list type="bullet">
379 376
404 401
405 402
406 <section name="Formatting" id="formatting"> 403 <section name="Formatting" id="formatting">
407 404
408 <para> 405 <para>
409 A number of formatting functions are provided by nginx. These functions support nginx-specific types: 406 The following formatting functions support nginx-specific types:
410 </para> 407 </para>
411 408
412 409
413 <para> 410 <para>
414 <list type="bullet"> 411 <list type="bullet">
435 432
436 </list> 433 </list>
437 </para> 434 </para>
438 435
439 <para> 436 <para>
440 The full list of formatting options, supported by these functions, can be found 437 The full list of formatting options, supported by these functions is
441 in <path>src/core/ngx_string.c</path>. Some of them are: 438 in <path>src/core/ngx_string.c</path>. Some of them are:
442 </para> 439 </para>
443 440
444 441
445 <programlisting> 442 <list type="bullet">
446 %O — off_t 443
447 %T — time_t 444 <listitem>
448 %z — size_t 445 <literal>%O</literal> — <literal>off_t</literal>
449 %i — ngx_int_t 446 </listitem>
450 %p — void * 447
451 %V — ngx_str_t * 448 <listitem>
452 %s — u_char * (null-terminated) 449 <literal>%T</literal> — <literal>time_t</literal>
453 %*s — size_t + u_char * 450 </listitem>
454 </programlisting> 451
455 452 <listitem>
456 <para> 453 <literal>%z</literal> — <literal>size_t</literal>
457 The ‘u’ modifier makes most types unsigned, ‘X’/‘x’ convert output to hex. 454 </listitem>
458 </para> 455
459 456 <listitem>
460 <para> 457 <literal>%i</literal> — <literal>ngx_int_t_t</literal>
461 Example: 458 </listitem>
459
460 <listitem>
461 <literal>%p</literal> — <literal>void *</literal>
462 </listitem>
463
464 <listitem>
465 <literal>%V</literal> — <literal>ngx_str_t *</literal>
466 </listitem>
467
468 <listitem>
469 <literal>%s</literal> — <literal>u_char *</literal> (null-terminated)
470 </listitem>
471
472 <listitem>
473 <literal>%*s</literal> — <literal>size_t + u_char *</literal>
474 </listitem>
475
476 </list>
477
478
479 <para>
480 You can prepend <literal>u</literal> on most types to make them unsigned.
481 To convert output to hex, use <literal>X</literal> or <literal>x</literal>.
482 </para>
483
484 <para>
485 For example:
462 486
463 <programlisting> 487 <programlisting>
464 u_char buf[NGX_INT_T_LEN]; 488 u_char buf[NGX_INT_T_LEN];
465 size_t len; 489 size_t len;
466 ngx_int_t n; 490 ngx_int_t n;
476 500
477 501
478 <section name="Numeric conversion" id="numeric_conversion"> 502 <section name="Numeric conversion" id="numeric_conversion">
479 503
480 <para> 504 <para>
481 Several functions for numeric conversion are implemented in nginx: 505 Several functions for numeric conversion are implemented in nginx.
482 </para> 506 The first four each convert a string of given length to a positive integer of
483 507 the indicated type.
484 <para> 508 They return <literal>NGX_ERROR</literal> on error.
509
485 <list type="bullet"> 510 <list type="bullet">
486 511
487 <listitem> 512 <listitem>
488 <literal>ngx_atoi(line, n)</literal> — converts a string of given length to a 513 <literal>ngx_atoi(line, n)</literal> — <literal>ngx_int_t</literal>
489 positive integer of type <literal>ngx_int_t</literal>. 514 </listitem>
490 Returns <literal>NGX_ERROR</literal> on error 515
491 </listitem> 516 <listitem>
492 517 <literal>ngx_atosz(line, n)</literal> — <literal>ssize_t</literal>
493 <listitem> 518 </listitem>
494 <literal>ngx_atosz(line, n)</literal> — same for <literal>ssize_t</literal> 519
495 type 520 <listitem>
496 </listitem> 521 <literal>ngx_atoof(line, n)</literal> — <literal>off_t</literal>
497 522 </listitem>
498 <listitem> 523
499 <literal>ngx_atoof(line, n)</literal> — same for <literal>off_t</literal> 524 <listitem>
500 type 525 <literal>ngx_atotm(line, n)</literal> — <literal>time_t</literal>
501 </listitem> 526 </listitem>
502 527
503 <listitem> 528 </list>
504 <literal>ngx_atotm(line, n)</literal> — same for <literal>time_t</literal> 529 </para>
505 type 530
506 </listitem> 531 <para>
507 532 There are two additional numeric conversion functions.
508 <listitem> 533 Like the first four, they return <literal>NGX_ERROR</literal> on error.
509 <literal>ngx_atofp(line, n, point)</literal> — converts a fixed point floating 534
535 <list type="bullet">
536
537 <listitem>
538 <literal>ngx_atofp(line, n, point)</literal> — Converts a fixed point floating
510 number of given length to a positive integer of type 539 number of given length to a positive integer of type
511 <literal>ngx_int_t</literal>. 540 <literal>ngx_int_t</literal>.
512 The result is shifted left by <literal>points</literal> decimal 541 The result is shifted left by <literal>point</literal> decimal
513 positions. The string representation of the number is expected to have no more 542 positions.
543 The string representation of the number is expected to have no more
514 than <literal>points</literal> fractional digits. 544 than <literal>points</literal> fractional digits.
515 Returns <literal>NGX_ERROR</literal> on error. For example, 545 For example, <literal>ngx_atofp("10.5", 4, 2)</literal> returns
516 <literal>ngx_atofp("10.5", 4, 2)</literal> returns <literal>1050</literal> 546 <literal>1050</literal>.
517 </listitem> 547 </listitem>
518 548
519 <listitem> 549 <listitem>
520 <literal>ngx_hextoi(line, n)</literal> — converts hexadecimal representation of 550 <literal>ngx_hextoi(line, n)</literal> — Converts a hexadecimal representation
521 a positive integer to <literal>ngx_int_t</literal>. Returns 551 of a positive integer to <literal>ngx_int_t</literal>.
522 <literal>NGX_ERROR</literal> on error
523 </listitem> 552 </listitem>
524 553
525 </list> 554 </list>
526 </para> 555 </para>
527 556
535 library. 564 library.
536 The corresponding header file is <path>src/core/ngx_regex.h</path>. 565 The corresponding header file is <path>src/core/ngx_regex.h</path>.
537 </para> 566 </para>
538 567
539 <para> 568 <para>
540 To use a regular expression for string matching, first, it needs to be 569 To use a regular expression for string matching, it first needs to be
541 compiled, this is usually done at configuration phase. 570 compiled, which is usually done at the configuration phase.
542 Note that since PCRE support is optional, all code using the interface must 571 Note that since PCRE support is optional, all code using the interface must
543 be protected by the surrounding <literal>NGX_PCRE</literal> macro: 572 be protected by the surrounding <literal>NGX_PCRE</literal> macro:
573
544 <programlisting> 574 <programlisting>
545 #if (NGX_PCRE) 575 #if (NGX_PCRE)
546 ngx_regex_t *re; 576 ngx_regex_t *re;
547 ngx_regex_compile_t rc; 577 ngx_regex_compile_t rc;
548 578
564 } 594 }
565 595
566 re = rc.regex; 596 re = rc.regex;
567 #endif 597 #endif
568 </programlisting> 598 </programlisting>
569 After successful compilation, <literal>ngx_regex_compile_t</literal> structure 599 After successful compilation, the <literal>captures</literal> and
570 fields <literal>captures</literal> and <literal>named_captures</literal> 600 <literal>named_captures</literal> fields in the
571 are filled with count of all and named captures respectively found in the 601 <literal>ngx_regex_compile_t</literal> structure contain the count of all
572 regular expression. 602 captures and named captures, respectively, found in the regular expression.
573 </para> 603 </para>
574 604
575 <para> 605 <para>
576 Later, the compiled regular expression may be used to match strings against it: 606 The compiled regular expression can then be used for matching against strings:
577 <programlisting> 607 <programlisting>
578 ngx_int_t n; 608 ngx_int_t n;
579 int captures[(1 + rc.captures) * 3]; 609 int captures[(1 + rc.captures) * 3];
580 610
581 ngx_str_t input = ngx_string("This is message 123. Codeword is 'foobar'."); 611 ngx_str_t input = ngx_string("This is message 123. Codeword is 'foobar'.");
590 } else { 620 } else {
591 /* some error */ 621 /* some error */
592 ngx_log_error(NGX_LOG_ALERT, log, 0, ngx_regex_exec_n " failed: %i", n); 622 ngx_log_error(NGX_LOG_ALERT, log, 0, ngx_regex_exec_n " failed: %i", n);
593 } 623 }
594 </programlisting> 624 </programlisting>
595 The arguments of <literal>ngx_regex_exec()</literal> are: the compiled regular 625 The arguments to <literal>ngx_regex_exec()</literal> are the compiled regular
596 expression <literal>re</literal>, string to match <literal>s</literal>, 626 expression <literal>re</literal>, the string to match <literal>s</literal>,
597 optional array of integers to hold found <literal>captures</literal> 627 an optional array of integers to hold any <literal>captures</literal> that are
598 and its <literal>size</literal>. 628 found, and the array's <literal>size</literal>.
599 The <literal>captures</literal> array size must be a multiple of three, 629 The size of the <literal>captures</literal> array must be a multiple of three,
600 per requirements of the 630 as required by the
601 <link url="http://www.pcre.org/original/doc/html/pcreapi.html">PCRE API</link>. 631 <link url="http://www.pcre.org/original/doc/html/pcreapi.html">PCRE API</link>.
602 In the example, its size is calculated from a total number of captures plus 632 In the example, the size is calculated from the total number of captures plus
603 one for the matched string itself. 633 <literal>1</literal>one for the matched string itself.
604 </para> 634 </para>
605 635
606 <para> 636 <para>
607 Now, if there are matches, captures may be accessed: 637 If there are matches, captures can be accessed as follows:
608 <programlisting> 638 <programlisting>
609 u_char *p; 639 u_char *p;
610 size_t size; 640 size_t size;
611 ngx_str_t name, value; 641 ngx_str_t name, value;
612 642
637 </para> 667 </para>
638 668
639 <para> 669 <para>
640 The <literal>ngx_regex_exec_array()</literal> function accepts the array of 670 The <literal>ngx_regex_exec_array()</literal> function accepts the array of
641 <literal>ngx_regex_elt_t</literal> elements (which are just compiled regular 671 <literal>ngx_regex_elt_t</literal> elements (which are just compiled regular
642 expressions with associated names), a string to match and a log. 672 expressions with associated names), a string to match, and a log.
643 The function will apply expressions from the array to the string until 673 The function applies expressions from the array to the string until
644 the match is found or no more expressions are left. 674 either a match is found or no more expressions are left.
645 The return value is <literal>NGX_OK</literal> in case of match and 675 The return value is <literal>NGX_OK</literal> when there is a match and
646 <literal>NGX_DECLINED</literal> otherwise, or <literal>NGX_ERROR</literal> 676 <literal>NGX_DECLINED</literal> otherwise, or <literal>NGX_ERROR</literal>
647 in case of error. 677 in case of error.
648 </para> 678 </para>
649 679
650 </section> 680 </section>
653 683
654 684
655 <section name="Time" id="time"> 685 <section name="Time" id="time">
656 686
657 <para> 687 <para>
658 The <literal>ngx_time_t</literal> structure represents time split into seconds 688 The <literal>ngx_time_t</literal> structure represents time with three separate
659 and milliseconds with specification of GMT offset: 689 types for seconds, milliseconds, and the GMT offset:
660 <programlisting> 690 <programlisting>
661 typedef struct { 691 typedef struct {
662 time_t sec; 692 time_t sec;
663 ngx_uint_t msec; 693 ngx_uint_t msec;
664 ngx_int_t gmtoff; 694 ngx_int_t gmtoff;
665 } ngx_time_t; 695 } ngx_time_t;
666 </programlisting> 696 </programlisting>
667 The <literal>ngx_tm_t</literal> is an alias for <literal>struct tm</literal> 697 The <literal>ngx_tm_t</literal> structure is an alias for
668 on UNIX platforms and <literal>SYSTEMTIME</literal> on Windows. 698 <literal>struct tm</literal> on UNIX platforms and <literal>SYSTEMTIME</literal>
669 </para> 699 on Windows.
670 700 </para>
671 <para> 701
672 To obtain current time, usually it is enough to access one of available global 702 <para>
673 variables, representing the cached time value in desired format. 703 To obtain the current time, it is usually sufficient to access one of the
674 The <literal>ngx_current_msec</literal> variable holds milliseconds elapsed 704 available global variables, representing the cached time value in the desired
675 since Epoch and truncated to <literal>ngx_msec_t</literal>. 705 format.
676 </para> 706 For example, the <literal>ngx_current_msec</literal> variable holds the number
677 707 of milliseconds elapsed since Epoch and truncated to
678 <para> 708 <literal>ngx_msec_t</literal>.
679 Available string representations are: 709 </para>
710
711 <para>
712 The available string representations are:
680 713
681 <list type="bullet"> 714 <list type="bullet">
682 715
683 <listitem> 716 <listitem>
684 <literal>ngx_cached_err_log_time</literal> — used in error log: 717 <literal>ngx_cached_err_log_time</literal> — Used in error log entries:
685 "<literal>1970/09/28 12:00:00</literal>" 718 <literal>"1970/09/28 12:00:00"</literal>
686 </listitem> 719 </listitem>
687 720
688 <listitem> 721 <listitem>
689 <literal>ngx_cached_http_log_time</literal> — used in HTTP access log: 722 <literal>ngx_cached_http_log_time</literal> — Used in HTTP access log entries:
690 "<literal>28/Sep/1970:12:00:00 +0600</literal>" 723 <literal>"28/Sep/1970:12:00:00 +0600"</literal>
691 </listitem> 724 </listitem>
692 725
693 <listitem> 726 <listitem>
694 <literal>ngx_cached_syslog_time</literal> — used in syslog: 727 <literal>ngx_cached_syslog_time</literal> — Used in syslog entries:
695 "<literal>Sep 28 12:00:00</literal>" 728 <literal>"Sep 28 12:00:00"</literal>
696 </listitem> 729 </listitem>
697 730
698 <listitem> 731 <listitem>
699 <literal>ngx_cached_http_time</literal> — used in HTTP for headers: 732 <literal>ngx_cached_http_time</literal> — Used in HTTP headers:
700 "<literal>Mon, 28 Sep 1970 06:00:00 GMT</literal>" 733 <literal>"Mon, 28 Sep 1970 06:00:00 GMT"</literal>
701 </listitem> 734 </listitem>
702 735
703 <listitem> 736 <listitem>
704 <literal>ngx_cached_http_log_iso8601</literal> — in the ISO 8601 737 <literal>ngx_cached_http_log_iso8601</literal> — The ISO 8601
705 standard format: 738 standard format:
706 "<literal>1970-09-28T12:00:00+06:00</literal>" 739 <literal>"1970-09-28T12:00:00+06:00"</literal>
707 </listitem> 740 </listitem>
708 741
709 </list> 742 </list>
710 </para> 743 </para>
711 744
712 <para> 745 <para>
713 The <literal>ngx_time()</literal> and <literal>ngx_timeofday()</literal> macros 746 The <literal>ngx_time()</literal> and <literal>ngx_timeofday()</literal> macros
714 returning current value of seconds are a preferred way to access cached 747 return the current time value in seconds and are the preferred way to access
715 time value. 748 the cached time value.
716 </para> 749 </para>
717 750
718 <para> 751 <para>
719 To obtain the time explicitly, <literal>ngx_gettimeofday()</literal> may 752 To obtain the time explicitly, use <literal>ngx_gettimeofday()</literal>,
720 be used, which updates its argument (pointer to 753 which updates its argument (pointer to
721 <literal>struct timeval</literal>). 754 <literal>struct timeval</literal>).
722 Time is always updated when nginx returns to event loop from system calls. 755 The time is always updated when nginx returns to the event loop from system
756 calls.
723 To update the time immediately, call <literal>ngx_time_update()</literal>, 757 To update the time immediately, call <literal>ngx_time_update()</literal>,
724 or <literal>ngx_time_sigsafe_update()</literal> if you need it in the 758 or <literal>ngx_time_sigsafe_update()</literal> if updating the time in the
725 signal handler context. 759 signal handler context.
726 </para> 760 </para>
727 761
728 <para> 762 <para>
729 The following functions convert <literal>time_t</literal> into broken-down time 763 The following functions convert <literal>time_t</literal> into the indicated
730 representation, either <literal>ngx_tm_t</literal> or 764 broken-down time representation.
731 <literal>struct tm</literal> for those with <literal>libc</literal> prefix: 765 The first function in each pair converts <literal>time_t</literal> to
766 <literal>ngx_tm_t</literal> and the second (with the <literal>_libc_</literal>
767 infix) to <literal>struct tm</literal>:
732 768
733 <list type="bullet"> 769 <list type="bullet">
734 770
735 <listitem> 771 <listitem>
736 <literal>ngx_gmtime(), ngx_libc_gmtime()</literal> — result time is UTC 772 <literal>ngx_gmtime(), ngx_libc_gmtime()</literal> — Time expressed as UTC
737 </listitem> 773 </listitem>
738 774
739 <listitem> 775 <listitem>
740 <literal>ngx_localtime(), ngx_libc_localtime()</literal> — result time is 776 <literal>ngx_localtime(), ngx_libc_localtime()</literal> — Time expressed
741 relative to the timezone 777 relative to the local time zone
742 </listitem> 778 </listitem>
743 779
744 </list> 780 </list>
745 781
746 The <literal>ngx_http_time(buf, time)</literal> returns string 782 The <literal>ngx_http_time(buf, time)</literal> function returns a string
747 representation suitable for use with HTTP headers (for example, 783 representation suitable for use in HTTP headers (for example,
748 "<literal>Mon, 28 Sep 1970 06:00:00 GMT</literal>"). 784 <literal>"Mon, 28 Sep 1970 06:00:00 GMT"</literal>).
749 Another possible conversion is provided by 785 The <literal>ngx_http_cookie_time(buf, time)</literal> returns a string
750 <literal>ngx_http_cookie_time(buf, time)</literal> that produces format suitable 786 representation function returns a string representation suitable
751 for HTTP cookies ("<literal>Thu, 31-Dec-37 23:55:55 GMT</literal>"). 787 for HTTP cookies (<literal>"Thu, 31-Dec-37 23:55:55 GMT"</literal>).
752 </para> 788 </para>
753 789
754 </section> 790 </section>
755 791
756 792
773 ngx_pool_t *pool; 809 ngx_pool_t *pool;
774 } ngx_array_t; 810 } ngx_array_t;
775 </programlisting> 811 </programlisting>
776 812
777 <para> 813 <para>
778 The elements of array are available through the <literal>elts</literal> field. 814 The elements of the array are available in the <literal>elts</literal> field.
779 The number of elements is held in the <literal>nelts</literal> field. 815 The <literal>nelts</literal> field holds the number of elements.
780 The <literal>size</literal> field holds the size of a single element and is set 816 The <literal>size</literal> field holds the size of a single element and is set
781 when initializing the array. 817 when the array is initialized.
782 </para> 818 </para>
783 819
784 <para> 820 <para>
785 An array can be created in a pool with the 821 Use the <literal>ngx_array_create(pool, n, size)</literal> call to create an
786 <literal>ngx_array_create(pool, n, size)</literal> call. 822 array in a pool, and the <literal>ngx_array_init(array, pool, n, size)</literal>
787 An already allocated array object can be initialized with the 823 call to initialize an array object that has already been allocated.
788 <literal>ngx_array_init(array, pool, n, size)</literal> call.
789 </para> 824 </para>
790 825
791 826
792 <programlisting> 827 <programlisting>
793 ngx_array_t *a, b; 828 ngx_array_t *a, b;
798 /* initialize string array for 10 elements */ 833 /* initialize string array for 10 elements */
799 ngx_array_init(&amp;b, pool, 10, sizeof(ngx_str_t)); 834 ngx_array_init(&amp;b, pool, 10, sizeof(ngx_str_t));
800 </programlisting> 835 </programlisting>
801 836
802 <para> 837 <para>
803 Adding elements to array are done with the following functions: 838 Use the following functions to add elements to an array:
804 </para> 839 </para>
805 840
806 <para> 841 <para>
807 <list type="bullet"> 842 <list type="bullet">
808 843
818 853
819 </list> 854 </list>
820 </para> 855 </para>
821 856
822 <para> 857 <para>
823 If currently allocated memory is not enough for new elements, a new memory for 858 If the currently allocated amount of memory is not large enough to accommodate
824 elements is allocated and existing elements are copied to that memory. 859 the new elements, a new block of memory is allocated and the existing elements
825 The new memory block is normally twice as large, as the existing one. 860 are copied to it.
861 The new memory block is normally twice as large as the existing one.
826 </para> 862 </para>
827 863
828 864
829 <programlisting> 865 <programlisting>
830 s = ngx_array_push(a); 866 s = ngx_array_push(a);
835 871
836 872
837 <section name="List" id="list"> 873 <section name="List" id="list">
838 874
839 <para> 875 <para>
840 List in nginx is a sequence of arrays, optimized for inserting a potentially 876 In nginx a list is a sequence of arrays, optimized for inserting a potentially
841 large number of items. The list type is defined as follows: 877 large number of items.
878 The <literal>ngx_list_t</literal> list type is defined as follows:
842 </para> 879 </para>
843 880
844 881
845 <programlisting> 882 <programlisting>
846 typedef struct { 883 typedef struct {
851 ngx_pool_t *pool; 888 ngx_pool_t *pool;
852 } ngx_list_t; 889 } ngx_list_t;
853 </programlisting> 890 </programlisting>
854 891
855 <para> 892 <para>
856 The actual items are stored in list parts, defined as follows: 893 The actual items are stored in list parts, which are defined as follows:
857 </para> 894 </para>
858 895
859 896
860 <programlisting> 897 <programlisting>
861 typedef struct ngx_list_part_s ngx_list_part_t; 898 typedef struct ngx_list_part_s ngx_list_part_t;
866 ngx_list_part_t *next; 903 ngx_list_part_t *next;
867 }; 904 };
868 </programlisting> 905 </programlisting>
869 906
870 <para> 907 <para>
871 Initially, a list must be initialized by calling 908 Before use, a list must be initialized by calling
872 <literal>ngx_list_init(list, pool, n, size)</literal> or created by calling 909 <literal>ngx_list_init(list, pool, n, size)</literal> or created by calling
873 <literal>ngx_list_create(pool, n, size)</literal>. 910 <literal>ngx_list_create(pool, n, size)</literal>.
874 Both functions receive the size of a single item and a number of items per list 911 Both functions take as arguments the size of a single item and a number of
875 part. 912 items per list part.
876 The <literal>ngx_list_push(list)</literal> function is used to add an item to the 913 To add an item to a list, use the <literal>ngx_list_push(list)</literal>
877 list. Iterating over the items is done by direct accessing the list fields, as 914 function.
878 seen in the example: 915 To iterate over the items, directly access the list fields as shown in the
916 example:
879 </para> 917 </para>
880 918
881 919
882 <programlisting> 920 <programlisting>
883 ngx_str_t *v; 921 ngx_str_t *v;
918 ngx_do_smth(&amp;v[i]); 956 ngx_do_smth(&amp;v[i]);
919 } 957 }
920 </programlisting> 958 </programlisting>
921 959
922 <para> 960 <para>
923 The primary use for the list in nginx is HTTP input and output headers. 961 Lists are primarily used for HTTP input and output headers.
924 </para> 962 </para>
925 963
926 <para> 964 <para>
927 The list does not support item removal. 965 Lists do not support item removal.
928 However, when needed, items can internally be marked as missing without actual 966 However, when needed, items can internally be marked as missing without actually
929 removing from the list. 967 being removed from the list.
930 For example, HTTP output headers which are stored as 968 For example, to mark HTTP output headers (which are stored as
931 <literal>ngx_table_elt_t</literal> objects, are marked as missing by setting 969 <literal>ngx_table_elt_t</literal> objects) as missing, set the
932 the <literal>hash</literal> field of <literal>ngx_table_elt_t</literal> to 970 <literal>hash</literal> field in <literal>ngx_table_elt_t</literal> to
933 zero. Such items are explicitly skipped, when iterating over the headers. 971 zero.
972 Items marked in this way are explicitly skipped when the headers are iterated
973 over.
934 </para> 974 </para>
935 975
936 </section> 976 </section>
937 977
938 978
939 <section name="Queue" id="queue"> 979 <section name="Queue" id="queue">
940 980
941 <para> 981 <para>
942 Queue in nginx is an intrusive doubly linked list, with each node defined as 982 In nginx a queue is an intrusive doubly linked list, with each node defined as
943 follows: 983 follows:
944 </para> 984 </para>
945 985
946 986
947 <programlisting> 987 <programlisting>
952 ngx_queue_t *next; 992 ngx_queue_t *next;
953 }; 993 };
954 </programlisting> 994 </programlisting>
955 995
956 <para> 996 <para>
957 The head queue node is not linked with any data. Before using, the list head 997 The head queue node is not linked with any data.
958 should be initialized with <literal>ngx_queue_init(q)</literal> call. 998 Use the <literal>ngx_queue_init(q)</literal> call to initialize the list head
999 before use.
959 Queues support the following operations: 1000 Queues support the following operations:
960 </para> 1001 </para>
961 1002
962 <para> 1003 <para>
963 <list type="bullet"> 1004 <list type="bullet">
964 1005
965 <listitem> 1006 <listitem>
966 <literal>ngx_queue_insert_head(h, x)</literal>, 1007 <literal>ngx_queue_insert_head(h, x)</literal>,
967 <literal>ngx_queue_insert_tail(h, x)</literal> — insert a new node 1008 <literal>ngx_queue_insert_tail(h, x)</literal> — Insert a new node
968 </listitem> 1009 </listitem>
969 1010
970 <listitem> 1011 <listitem>
971 <literal>ngx_queue_remove(x)</literal> — remove a queue node 1012 <literal>ngx_queue_remove(x)</literal> — Remove a queue node
972 </listitem> 1013 </listitem>
973 1014
974 <listitem> 1015 <listitem>
975 <literal>ngx_queue_split(h, q, n)</literal> — split a queue at a node, 1016 <literal>ngx_queue_split(h, q, n)</literal> — Split a queue at a node,
976 queue tail is returned in a separate queue 1017 returning the queue tail in a separate queue
977 </listitem> 1018 </listitem>
978 1019
979 <listitem> 1020 <listitem>
980 <literal>ngx_queue_add(h, n)</literal> — add second queue to the first queue 1021 <literal>ngx_queue_add(h, n)</literal> — Add a second queue to the first queue
981 </listitem> 1022 </listitem>
982 1023
983 <listitem> 1024 <listitem>
984 <literal>ngx_queue_head(h)</literal>, 1025 <literal>ngx_queue_head(h)</literal>,
985 <literal>ngx_queue_last(h)</literal> — get first or last queue node 1026 <literal>ngx_queue_last(h)</literal> — Get first or last queue node
986 </listitem> 1027 </listitem>
987 1028
988 <listitem> 1029 <listitem>
989 <literal>ngx_queue_sentinel(h)</literal> 1030 <literal>ngx_queue_sentinel(h)</literal> - Get a queue sentinel object to end
990 - get a queue sentinel object to end iteration at 1031 iteration at
991 </listitem> 1032 </listitem>
992 1033
993 <listitem> 1034 <listitem>
994 <literal>ngx_queue_data(q, type, link)</literal> — get reference to the beginning of a 1035 <literal>ngx_queue_data(q, type, link)</literal> — Get a reference to the
995 queue node data structure, considering the queue field offset in it 1036 beginning of a queue node data structure, considering the queue field offset in
1037 it
996 </listitem> 1038 </listitem>
997 1039
998 </list> 1040 </list>
999 </para> 1041 </para>
1000 1042
1001 <para> 1043 <para>
1002 Example: 1044 An example:
1003 </para> 1045 </para>
1004 1046
1005 1047
1006 <programlisting> 1048 <programlisting>
1007 typedef struct { 1049 typedef struct {
1059 } my_node_t; 1101 } my_node_t;
1060 </programlisting> 1102 </programlisting>
1061 1103
1062 <para> 1104 <para>
1063 To deal with a tree as a whole, you need two nodes: root and sentinel. 1105 To deal with a tree as a whole, you need two nodes: root and sentinel.
1064 Typically, they are added to some custom structure, thus allowing to 1106 Typically, they are added to a custom structure, allowing you to
1065 organize your data into a tree which leaves contain a link to or embed 1107 organize your data into a tree in which the leaves contain a link to or embed
1066 your data. 1108 your data.
1067 </para> 1109 </para>
1068 1110
1069 <para> 1111 <para>
1070 To initialize a tree: 1112 To initialize a tree:
1076 1118
1077 ngx_rbtree_init(&amp;root.rbtree, &amp;root.sentinel, insert_value_function); 1119 ngx_rbtree_init(&amp;root.rbtree, &amp;root.sentinel, insert_value_function);
1078 </programlisting> 1120 </programlisting>
1079 1121
1080 <para> 1122 <para>
1081 The <literal>insert_value_function</literal> is a function that is 1123 To traverse a tree and insert new values, use the
1082 responsible for traversing the tree and inserting new values into correct 1124 "<literal>insert_value</literal>" functions.
1083 place. 1125 For example, the <literal>ngx_str_rbtree_insert_value</literal> function deals
1084 For example, the <literal>ngx_str_rbtree_insert_value</literal> functions is 1126 with the <literal>ngx_str_t</literal> type.
1085 designed to deal with <literal>ngx_str_t</literal> type. 1127 Its arguments are pointers to a root node of an insertion, the newly created
1128 node to be added, and a tree sentinel.
1086 </para> 1129 </para>
1087 1130
1088 1131
1089 <programlisting> 1132 <programlisting>
1090 void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp, 1133 void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp,
1091 ngx_rbtree_node_t *node, 1134 ngx_rbtree_node_t *node,
1092 ngx_rbtree_node_t *sentinel) 1135 ngx_rbtree_node_t *sentinel)
1093 </programlisting> 1136 </programlisting>
1094 1137
1095 <para>
1096 Its arguments are pointers to a root node of an insertion, newly created node
1097 to be added, and a tree sentinel.
1098 </para>
1099 1138
1100 <para> 1139 <para>
1101 The traversal is pretty straightforward and can be demonstrated with the 1140 The traversal is pretty straightforward and can be demonstrated with the
1102 following lookup function pattern: 1141 following lookup function pattern:
1103 </para> 1142 </para>
1141 return NULL; 1180 return NULL;
1142 } 1181 }
1143 </programlisting> 1182 </programlisting>
1144 1183
1145 <para> 1184 <para>
1146 The <literal>compare()</literal> is a classic comparator function returning 1185 The <literal>compare()</literal> function is a classic comparator function that
1147 value less, equal or greater than zero. To speed up lookups and avoid comparing 1186 returns a value less than, equal to, or greater than zero.
1148 user objects that can be big, integer hash field is used. 1187 To speed up lookups and avoid comparing user objects that can be big, an integer
1188 hash field is used.
1149 </para> 1189 </para>
1150 1190
1151 <para> 1191 <para>
1152 To add a node to a tree, allocate a new node, initialize it and call 1192 To add a node to a tree, allocate a new node, initialize it and call
1153 <literal>ngx_rbtree_insert()</literal>: 1193 <literal>ngx_rbtree_insert()</literal>:
1166 1206
1167 ngx_rbtree_insert(&amp;root->rbtree, node); 1207 ngx_rbtree_insert(&amp;root->rbtree, node);
1168 </programlisting> 1208 </programlisting>
1169 1209
1170 <para> 1210 <para>
1171 to remove a node: 1211 To remove a node, call the <literal>ngx_rbtree_delete()</literal> function:
1172 </para> 1212 </para>
1173 1213
1174 1214
1175 <programlisting> 1215 <programlisting>
1176 ngx_rbtree_delete(&amp;root->rbtree, node); 1216 ngx_rbtree_delete(&amp;root->rbtree, node);
1180 1220
1181 <section name="Hash" id="hash"> 1221 <section name="Hash" id="hash">
1182 1222
1183 <para> 1223 <para>
1184 Hash table functions are declared in <path>src/core/ngx_hash.h</path>. 1224 Hash table functions are declared in <path>src/core/ngx_hash.h</path>.
1185 Exact and wildcard matching is supported. 1225 Both exact and wildcard matching are supported.
1186 The latter requires extra setup and is described in a separate section below. 1226 The latter requires extra setup and is described in a separate section below.
1187 </para> 1227 </para>
1188 1228
1189 <para> 1229 <para>
1190 To initialize a hash, one needs to know the number of elements in advance, 1230 Before initializing a hash, you need to know the number of elements it will
1191 so that nginx can build the hash optimally. 1231 hold so that nginx can build it optimally.
1192 Two parameters that need to be configured are <literal>max_size</literal> 1232 Two parameters that need to be configured are <literal>max_size</literal>
1193 and <literal>bucket_size</literal>. 1233 and <literal>bucket_size</literal>, as detailed in a separate
1194 The details of setting up these are provided in a separate
1195 <link doc="../hash.xml">document</link>. 1234 <link doc="../hash.xml">document</link>.
1196 Usually, these two parameters are configurable by user. 1235 They are usually configurable by the user.
1197 Hash initialization settings are stored as the 1236 Hash initialization settings are stored with the
1198 <literal>ngx_hash_init_t</literal> type, 1237 <literal>ngx_hash_init_t</literal> type, and the hash itself is
1199 and the hash itself is <literal>ngx_hash_t</literal>: 1238 <literal>ngx_hash_t</literal>:
1200 <programlisting> 1239 <programlisting>
1201 ngx_hash_t foo_hash; 1240 ngx_hash_t foo_hash;
1202 ngx_hash_init_t hash; 1241 ngx_hash_init_t hash;
1203 1242
1204 hash.hash = &amp;foo_hash; 1243 hash.hash = &amp;foo_hash;
1207 hash.bucket_size = ngx_align(64, ngx_cacheline_size); 1246 hash.bucket_size = ngx_align(64, ngx_cacheline_size);
1208 hash.name = "foo_hash"; 1247 hash.name = "foo_hash";
1209 hash.pool = cf-&gt;pool; 1248 hash.pool = cf-&gt;pool;
1210 hash.temp_pool = cf-&gt;temp_pool; 1249 hash.temp_pool = cf-&gt;temp_pool;
1211 </programlisting> 1250 </programlisting>
1212 The <literal>key</literal> is a pointer to a function that creates hash integer 1251 The <literal>key</literal> is a pointer to a function that creates the hash
1213 key from a string. 1252 integer key from a string.
1214 Two generic functions are provided: 1253 There are two generic key-creation functions:
1215 <literal>ngx_hash_key(data, len)</literal> and 1254 <literal>ngx_hash_key(data, len)</literal> and
1216 <literal>ngx_hash_key_lc(data, len)</literal>. 1255 <literal>ngx_hash_key_lc(data, len)</literal>.
1217 The latter converts a string to lowercase and thus requires the passed string to 1256 The latter converts a string to all lowercase characters, so the passed string
1218 be writable. 1257 must be writeable.
1219 If this is not true, <literal>NGX_HASH_READONLY_KEY</literal> flag 1258 If that is not true, pass the <literal>NGX_HASH_READONLY_KEY</literal> flag
1220 may be passed to the function, initializing array keys (see below). 1259 to the function, initializing the key array (see below).
1221 </para> 1260 </para>
1222 1261
1223 <para> 1262 <para>
1224 The hash keys are stored in <literal>ngx_hash_keys_arrays_t</literal> and 1263 The hash keys are stored in <literal>ngx_hash_keys_arrays_t</literal> and
1225 are initialized with <literal>ngx_hash_keys_array_init(arr, type)</literal>: 1264 are initialized with <literal>ngx_hash_keys_array_init(arr, type)</literal>:
1265 The second parameter (<literal>type</literal>) controls the amount of resources
1266 preallocated for the hash and can be either <literal>NGX_HASH_SMALL</literal> or
1267 <literal>NGX_HASH_LARGE</literal>.
1268 The latter is appropriate if you expect the hash to contain thousands of
1269 elements.
1270
1226 <programlisting> 1271 <programlisting>
1227 ngx_hash_keys_arrays_t foo_keys; 1272 ngx_hash_keys_arrays_t foo_keys;
1228 1273
1229 foo_keys.pool = cf-&gt;pool; 1274 foo_keys.pool = cf-&gt;pool;
1230 foo_keys.temp_pool = cf-&gt;temp_pool; 1275 foo_keys.temp_pool = cf-&gt;temp_pool;
1231 1276
1232 ngx_hash_keys_array_init(&amp;foo_keys, NGX_HASH_SMALL); 1277 ngx_hash_keys_array_init(&amp;foo_keys, NGX_HASH_SMALL);
1233 </programlisting> 1278 </programlisting>
1234 The second parameter can be either <literal>NGX_HASH_SMALL</literal> or 1279 </para>
1235 <literal>NGX_HASH_LARGE</literal> and controls the amount of preallocated 1280
1236 resources for the hash. 1281 <para>
1237 If you expect the hash to contain thousands elements, 1282 To insert keys into a hash keys array, use the
1238 use <literal>NGX_HASH_LARGE</literal>. 1283 <literal>ngx_hash_add_key(keys_array, key, value, flags)</literal> function:
1239 </para>
1240
1241 <para>
1242 The <literal>ngx_hash_add_key(keys_array, key, value, flags)</literal>
1243 function is used to insert keys into hash keys array;
1244 <programlisting> 1284 <programlisting>
1245 ngx_str_t k1 = ngx_string("key1"); 1285 ngx_str_t k1 = ngx_string("key1");
1246 ngx_str_t k2 = ngx_string("key2"); 1286 ngx_str_t k2 = ngx_string("key2");
1247 1287
1248 ngx_hash_add_key(&amp;foo_keys, &amp;k1, &amp;my_data_ptr_1, NGX_HASH_READONLY_KEY); 1288 ngx_hash_add_key(&amp;foo_keys, &amp;k1, &amp;my_data_ptr_1, NGX_HASH_READONLY_KEY);
1249 ngx_hash_add_key(&amp;foo_keys, &amp;k2, &amp;my_data_ptr_2, NGX_HASH_READONLY_KEY); 1289 ngx_hash_add_key(&amp;foo_keys, &amp;k2, &amp;my_data_ptr_2, NGX_HASH_READONLY_KEY);
1250 </programlisting> 1290 </programlisting>
1251 </para> 1291 </para>
1252 1292
1253 <para> 1293 <para>
1254 Now, the hash table may be built using the call to 1294 To build the hash table, call the
1255 <literal>ngx_hash_init(hinit, key_names, nelts)</literal>: 1295 <literal>ngx_hash_init(hinit, key_names, nelts)</literal> function:
1256 1296
1257 <programlisting> 1297 <programlisting>
1258 ngx_hash_init(&amp;hash, foo_keys.keys.elts, foo_keys.keys.nelts); 1298 ngx_hash_init(&amp;hash, foo_keys.keys.elts, foo_keys.keys.nelts);
1259 </programlisting> 1299 </programlisting>
1260 1300
1261 This may fail, if <literal>max_size</literal> or <literal>bucket_size</literal> 1301 The function fails if <literal>max_size</literal> or
1262 parameters are not big enough. 1302 <literal>bucket_size</literal> parameters are not big enough.
1263 When the hash is built, <literal>ngx_hash_find(hash, key, name, len)</literal> 1303 </para>
1264 function may be used to look up elements: 1304
1305 <para>
1306 When the hash is built, use the
1307 <literal>ngx_hash_find(hash, key, name, len)</literal> function to look up
1308 elements:
1265 <programlisting> 1309 <programlisting>
1266 my_data_t *data; 1310 my_data_t *data;
1267 ngx_uint_t key; 1311 ngx_uint_t key;
1268 1312
1269 key = ngx_hash_key(k1.data, k1.len); 1313 key = ngx_hash_key(k1.data, k1.len);
1277 </para> 1321 </para>
1278 1322
1279 <section name="Wildcard matching" id="wildcard_matching"> 1323 <section name="Wildcard matching" id="wildcard_matching">
1280 1324
1281 <para> 1325 <para>
1282 To create a hash that works with wildcards, 1326 To create a hash that works with wildcards, use the
1283 <literal>ngx_hash_combined_t</literal> type is used. 1327 <literal>ngx_hash_combined_t</literal> type.
1284 It includes the hash type described above and has two additional keys arrays: 1328 It includes the hash type described above and has two additional keys arrays:
1285 <literal>dns_wc_head</literal> and <literal>dns_wc_tail</literal>. 1329 <literal>dns_wc_head</literal> and <literal>dns_wc_tail</literal>.
1286 The initialization of basic properties is done similarly to a usual hash: 1330 The initialization of basic properties is similar to a regular hash:
1287 <programlisting> 1331 <programlisting>
1288 ngx_hash_init_t hash 1332 ngx_hash_init_t hash
1289 ngx_hash_combined_t foo_hash; 1333 ngx_hash_combined_t foo_hash;
1290 1334
1291 hash.hash = &amp;foo_hash.hash; 1335 hash.hash = &amp;foo_hash.hash;
1300 /* k1 = ".example.org"; */ 1344 /* k1 = ".example.org"; */
1301 /* k2 = "foo.*"; */ 1345 /* k2 = "foo.*"; */
1302 ngx_hash_add_key(&amp;foo_keys, &amp;k1, &amp;data1, NGX_HASH_WILDCARD_KEY); 1346 ngx_hash_add_key(&amp;foo_keys, &amp;k1, &amp;data1, NGX_HASH_WILDCARD_KEY);
1303 ngx_hash_add_key(&amp;foo_keys, &amp;k2, &amp;data2, NGX_HASH_WILDCARD_KEY); 1347 ngx_hash_add_key(&amp;foo_keys, &amp;k2, &amp;data2, NGX_HASH_WILDCARD_KEY);
1304 </programlisting> 1348 </programlisting>
1305 The function recognizes wildcards and adds keys into corresponding arrays. 1349 The function recognizes wildcards and adds keys into the corresponding arrays.
1306 Please refer to the 1350 Please refer to the
1307 <link doc="../http/ngx_http_map_module.xml" id="map"/> module 1351 <link doc="../http/ngx_http_map_module.xml" id="map"/> module
1308 documentation for the description of the wildcard syntax and 1352 documentation for the description of the wildcard syntax and the
1309 matching algorithm. 1353 matching algorithm.
1310 </para> 1354 </para>
1311 1355
1312 <para> 1356 <para>
1313 Depending on the contents of added keys, you may need to initialize up to three 1357 Depending on the contents of added keys, you may need to initialize up to three
1314 keys arrays: one for exact matching (described above), and two for matching 1358 key arrays: one for exact matching (described above), and two more to enable
1315 starting from head or tail of a string: 1359 matching starting from the head or tail of a string:
1316 <programlisting> 1360 <programlisting>
1317 if (foo_keys.dns_wc_head.nelts) { 1361 if (foo_keys.dns_wc_head.nelts) {
1318 1362
1319 ngx_qsort(foo_keys.dns_wc_head.elts, 1363 ngx_qsort(foo_keys.dns_wc_head.elts,
1320 (size_t) foo_keys.dns_wc_head.nelts, 1364 (size_t) foo_keys.dns_wc_head.nelts,
1362 1406
1363 1407
1364 <section name="Heap" id="heap"> 1408 <section name="Heap" id="heap">
1365 1409
1366 <para> 1410 <para>
1367 To allocate memory from system heap, the following functions are provided by 1411 To allocate memory from system heap, use the following functions:
1368 nginx:
1369 </para> 1412 </para>
1370 1413
1371 <para> 1414 <para>
1372 <list type="bullet"> 1415 <list type="bullet">
1373 1416
1374 <listitem> 1417 <listitem>
1375 <literal>ngx_alloc(size, log)</literal> — allocate memory from system heap. 1418 <literal>ngx_alloc(size, log)</literal> — Allocate memory from system heap.
1376 This is a wrapper around <literal>malloc()</literal> with logging support. 1419 This is a wrapper around <literal>malloc()</literal> with logging support.
1377 Allocation error and debugging information is logged to <literal>log</literal> 1420 Allocation error and debugging information is logged to <literal>log</literal>.
1378 </listitem> 1421 </listitem>
1379 1422
1380 <listitem> 1423 <listitem>
1381 <literal>ngx_calloc(size, log)</literal> — same as 1424 <literal>ngx_calloc(size, log)</literal> — Allocate memory from system heap
1382 <literal>ngx_alloc()</literal>, but memory is filled with zeroes after 1425 like <literal>ngx_alloc()</literal>, but fill memory with zeros after
1383 allocation 1426 allocation.
1384 </listitem> 1427 </listitem>
1385 1428
1386 <listitem> 1429 <listitem>
1387 <literal>ngx_memalign(alignment, size, log)</literal> — allocate aligned memory 1430 <literal>ngx_memalign(alignment, size, log)</literal> — Allocate aligned memory
1388 from system heap. This is a wrapper around <literal>posix_memalign()</literal> 1431 from system heap.
1389 on those platforms which provide it. 1432 This is a wrapper around <literal>posix_memalign()</literal>
1433 on those platforms that provide that function.
1390 Otherwise implementation falls back to <literal>ngx_alloc()</literal> which 1434 Otherwise implementation falls back to <literal>ngx_alloc()</literal> which
1391 provides maximum alignment 1435 provides maximum alignment.
1392 </listitem> 1436 </listitem>
1393 1437
1394 <listitem> 1438 <listitem>
1395 <literal>ngx_free(p)</literal> — free allocated memory. 1439 <literal>ngx_free(p)</literal> — Free allocated memory.
1396 This is a wrapper around <literal>free()</literal> 1440 This is a wrapper around <literal>free()</literal>
1397 </listitem> 1441 </listitem>
1398 1442
1399 </list> 1443 </list>
1400 </para> 1444 </para>
1403 1447
1404 1448
1405 <section name="Pool" id="pool"> 1449 <section name="Pool" id="pool">
1406 1450
1407 <para> 1451 <para>
1408 Most nginx allocations are done in pools. Memory allocated in an nginx pool is 1452 Most nginx allocations are done in pools.
1409 freed automatically when the pool in destroyed. This provides good 1453 Memory allocated in an nginx pool is freed automatically when the pool is
1410 allocation performance and makes memory control easy. 1454 destroyed.
1411 </para> 1455 This provides good allocation performance and makes memory control easy.
1412 1456 </para>
1413 <para> 1457
1414 A pool internally allocates objects in continuous blocks of memory. Once a 1458 <para>
1415 block is full, a new one is allocated and added to the pool memory 1459 A pool internally allocates objects in continuous blocks of memory.
1416 block list. When a large allocation is requested which does not fit into 1460 Once a block is full, a new one is allocated and added to the pool memory
1417 a block, such allocation is forwarded to the system allocator and the 1461 block list.
1462 When the requested allocation is too large to fit into a block, the request
1463 is forwarded to the system allocator and the
1418 returned pointer is stored in the pool for further deallocation. 1464 returned pointer is stored in the pool for further deallocation.
1419 </para> 1465 </para>
1420 1466
1421 <para> 1467 <para>
1422 Nginx pool has the type <literal>ngx_pool_t</literal>. 1468 The type for nginx pools is <literal>ngx_pool_t</literal>.
1423 The following operations are supported: 1469 The following operations are supported:
1424 </para> 1470 </para>
1425 1471
1426 <para> 1472 <para>
1427 <list type="bullet"> 1473 <list type="bullet">
1428 1474
1429 <listitem> 1475 <listitem>
1430 <literal>ngx_create_pool(size, log)</literal> — create a pool with given 1476 <literal>ngx_create_pool(size, log)</literal> — Create a pool with specified
1431 block size. The pool object returned is allocated in the pool as well. 1477 block size.
1432 </listitem> 1478 The pool object returned is allocated in the pool as well.
1433 1479 </listitem>
1434 <listitem> 1480
1435 <literal>ngx_destroy_pool(pool)</literal> — free all pool memory, including 1481 <listitem>
1482 <literal>ngx_destroy_pool(pool)</literal> — Free all pool memory, including
1436 the pool object itself. 1483 the pool object itself.
1437 </listitem> 1484 </listitem>
1438 1485
1439 <listitem> 1486 <listitem>
1440 <literal>ngx_palloc(pool, size)</literal> — allocate aligned memory from pool 1487 <literal>ngx_palloc(pool, size)</literal> — Allocate aligned memory from the
1441 </listitem> 1488 specified pool.
1442 1489 </listitem>
1443 <listitem> 1490
1444 <literal>ngx_pcalloc(pool, size)</literal> — allocated aligned memory 1491 <listitem>
1445 from pool and fill it with zeroes 1492 <literal>ngx_pcalloc(pool, size)</literal> — Allocate aligned memory
1446 </listitem> 1493 from the specified pool and fill it with zeroes.
1447 1494 </listitem>
1448 <listitem> 1495
1449 <literal>ngx_pnalloc(pool, size)</literal> — allocate unaligned memory from pool. 1496 <listitem>
1450 Mostly used for allocating strings 1497 <literal>ngx_pnalloc(pool, size)</literal> — Allocate unaligned memory from the
1451 </listitem> 1498 specified pool.
1452 1499 Mostly used for allocating strings.
1453 <listitem> 1500 </listitem>
1454 <literal>ngx_pfree(pool, p)</literal> — free memory, previously allocated 1501
1455 in the pool. 1502 <listitem>
1456 Only allocations, forwarded to the system allocator, can be freed. 1503 <literal>ngx_pfree(pool, p)</literal> — Free memory that was previously
1504 allocated in the specified pool.
1505 Only allocations that result from requests forwarded to the system allocator
1506 can be freed.
1457 </listitem> 1507 </listitem>
1458 1508
1459 </list> 1509 </list>
1460 </para> 1510 </para>
1461 1511
1475 if (p == NULL) { /* error */ } 1525 if (p == NULL) { /* error */ }
1476 ngx_memcpy(p, "foo", 3); 1526 ngx_memcpy(p, "foo", 3);
1477 </programlisting> 1527 </programlisting>
1478 1528
1479 <para> 1529 <para>
1480 Since chain links <literal>ngx_chain_t</literal> are actively used in nginx, 1530 Chain links (<literal>ngx_chain_t</literal>) are actively used in nginx,
1481 nginx pool provides a way to reuse them. 1531 so the nginx pool implementation provides a way to reuse them.
1482 The <literal>chain</literal> field of <literal>ngx_pool_t</literal> keeps a 1532 The <literal>chain</literal> field of <literal>ngx_pool_t</literal> keeps a
1483 list of previously allocated links ready for reuse. For efficient allocation of 1533 list of previously allocated links ready for reuse.
1484 a chain link in a pool, the function 1534 For efficient allocation of a chain link in a pool, use the
1485 <literal>ngx_alloc_chain_link(pool)</literal> should be used. 1535 <literal>ngx_alloc_chain_link(pool)</literal> function.
1486 This function looks up a free chain link in the pool list and only if it's 1536 This function looks up a free chain link in the pool list and allocates a new
1487 empty allocates a new one. To free a link <literal>ngx_free_chain(pool, cl)</literal> 1537 chain link if the pool list is empty.
1488 should be called. 1538 To free a link, call the <literal>ngx_free_chain(pool, cl)</literal> function.
1489 </para> 1539 </para>
1490 1540
1491 <para> 1541 <para>
1492 Cleanup handlers can be registered in a pool. 1542 Cleanup handlers can be registered in a pool.
1493 Cleanup handler is a callback with an argument which is called when pool is 1543 A cleanup handler is a callback with an argument which is called when pool is
1494 destroyed. 1544 destroyed.
1495 Pool is usually tied with a specific nginx object (like HTTP request) and 1545 A pool is usually tied to a specific nginx object (like an HTTP request) and is
1496 destroyed in the end of that object’s lifetime, releasing the object itself. 1546 destroyed when the object reaches the end of its lifetime.
1497 Registering a pool cleanup is a convenient way to release resources, close file 1547 Registering a pool cleanup is a convenient way to release resources, close
1498 descriptors or make final adjustments to shared data, associated with the main 1548 file descriptors or make final adjustments to the shared data associated with
1499 object. 1549 the main object.
1500 </para> 1550 </para>
1501 1551
1502 <para> 1552 <para>
1503 A pool cleanup is registered by calling <literal>ngx_pool_cleanup_add(pool, 1553 To register a pool cleanup, call
1504 size)</literal> which returns <literal>ngx_pool_cleanup_t</literal> pointer to 1554 <literal>ngx_pool_cleanup_add(pool, size)</literal>, which returns a
1505 be filled by the caller. The <literal>size</literal> argument allows allocating 1555 <literal>ngx_pool_cleanup_t</literal> pointer to
1506 context for the cleanup handler. 1556 be filled in by the caller.
1557 Use the <literal>size</literal> argument to allocate context for the cleanup
1558 handler.
1507 </para> 1559 </para>
1508 1560
1509 1561
1510 <programlisting> 1562 <programlisting>
1511 ngx_pool_cleanup_t *cln; 1563 ngx_pool_cleanup_t *cln;
1532 1584
1533 <section name="Shared memory" id="shared_memory"> 1585 <section name="Shared memory" id="shared_memory">
1534 1586
1535 <para> 1587 <para>
1536 Shared memory is used by nginx to share common data between processes. 1588 Shared memory is used by nginx to share common data between processes.
1537 Function <literal>ngx_shared_memory_add(cf, name, size, tag)</literal> adds a 1589 The <literal>ngx_shared_memory_add(cf, name, size, tag)</literal> function adds
1538 new shared memory entry <literal>ngx_shm_zone_t</literal> to the cycle. The 1590 a new shared memory entry <literal>ngx_shm_zone_t</literal> to a cycle.
1539 function receives <literal>name</literal> and <literal>size</literal> of the 1591 The function receives the <literal>name</literal> and <literal>size</literal>
1540 zone. 1592 of the zone.
1541 Each shared zone must have a unique name. 1593 Each shared zone must have a unique name.
1542 If a shared zone entry with the provided name exists, the old zone entry is 1594 If a shared zone entry with the provided <literal>name</literal> and
1543 reused, if its tag value matches too. 1595 <literal>tag</literal> already exists, the existing zone entry is reused.
1544 Mismatched tag is considered an error. 1596 The function fails with an error if an existing entry with the same name has a
1545 Usually, the address of the module structure is passed as tag, making it 1597 different tag.
1546 possible to reuse shared zones by name within one nginx module. 1598 Usually, the address of the module structure is passed as
1599 <literal>tag</literal>, making it possible to reuse shared zones by name within
1600 one nginx module.
1547 </para> 1601 </para>
1548 1602
1549 <para> 1603 <para>
1550 The shared memory entry structure <literal>ngx_shm_zone_t</literal> has the 1604 The shared memory entry structure <literal>ngx_shm_zone_t</literal> has the
1551 following fields: 1605 following fields:
1553 1607
1554 <para> 1608 <para>
1555 <list type="bullet"> 1609 <list type="bullet">
1556 1610
1557 <listitem> 1611 <listitem>
1558 <literal>init</literal> — initialization callback, called after shared zone is 1612 <literal>init</literal> — Initialization callback, called after the shared zone
1559 mapped to actual memory 1613 is mapped to actual memory
1560 </listitem> 1614 </listitem>
1561 1615
1562 <listitem> 1616 <listitem>
1563 <literal>data</literal> — data context, used to pass arbitrary data to the 1617 <literal>data</literal> — Data context, used to pass arbitrary data to the
1564 <literal>init</literal> callback 1618 <literal>init</literal> callback
1565 </listitem> 1619 </listitem>
1566 1620
1567 <listitem> 1621 <listitem>
1568 <literal>noreuse</literal> — flag, disabling shared zone reuse from the 1622 <literal>noreuse</literal> — Flag that disables reuse of a shared zone from the
1569 old cycle 1623 old cycle
1570 </listitem> 1624 </listitem>
1571 1625
1572 <listitem> 1626 <listitem>
1573 <literal>tag</literal> — shared zone tag 1627 <literal>tag</literal> — Shared zone tag
1574 </listitem> 1628 </listitem>
1575 1629
1576 <listitem> 1630 <listitem>
1577 <literal>shm</literal> — platform-specific object of type 1631 <literal>shm</literal> — Platform-specific object of type
1578 <literal>ngx_shm_t</literal>, having at least the following fields: 1632 <literal>ngx_shm_t</literal>, having at least the following fields:
1579 <list type="bullet"> 1633 <list type="bullet">
1580 1634
1581 <listitem> 1635 <listitem>
1582 <literal>addr</literal> — mapped shared memory address, initially NULL 1636 <literal>addr</literal> — Mapped shared memory address, initially NULL
1583 </listitem> 1637 </listitem>
1584 1638
1585 <listitem> 1639 <listitem>
1586 <literal>size</literal> — shared memory size 1640 <literal>size</literal> — Shared memory size
1587 </listitem> 1641 </listitem>
1588 1642
1589 <listitem> 1643 <listitem>
1590 <literal>name</literal> — shared memory name 1644 <literal>name</literal> — Shared memory name
1591 </listitem> 1645 </listitem>
1592 1646
1593 <listitem> 1647 <listitem>
1594 <literal>log</literal> — shared memory log 1648 <literal>log</literal> — Shared memory log
1595 </listitem> 1649 </listitem>
1596 1650
1597 <listitem> 1651 <listitem>
1598 <literal>exists</literal> — flag, showing that shared memory was inherited 1652 <literal>exists</literal> — Flag that indicates shared memory was inherited
1599 from the master process (Windows-specific) 1653 from the master process (Windows-specific)
1600 </listitem> 1654 </listitem>
1601 1655
1602 </list> 1656 </list>
1603 </listitem> 1657 </listitem>
1605 </list> 1659 </list>
1606 </para> 1660 </para>
1607 1661
1608 <para> 1662 <para>
1609 Shared zone entries are mapped to actual memory in 1663 Shared zone entries are mapped to actual memory in
1610 <literal>ngx_init_cycle()</literal> after configuration is parsed. 1664 <literal>ngx_init_cycle()</literal> after the configuration is parsed.
1611 On POSIX systems, <literal>mmap()</literal> syscall is used to create shared 1665 On POSIX systems, the <literal>mmap()</literal> syscall is used to create the
1612 anonymous mapping. 1666 shared anonymous mapping.
1613 On Windows, <literal>CreateFileMapping()/MapViewOfFileEx()</literal> pair is 1667 On Windows, the <literal>CreateFileMapping()</literal>/
1614 used. 1668 <literal>MapViewOfFileEx()</literal> pair is used.
1615 </para> 1669 </para>
1616 1670
1617 <para> 1671 <para>
1618 For allocating in shared memory, nginx provides slab pool 1672 For allocating in shared memory, nginx provides the slab pool
1619 <literal>ngx_slab_pool_t</literal>. 1673 <literal>ngx_slab_pool_t</literal> type.
1620 In each nginx shared zone, a slab pool is automatically created for allocating 1674 A slab pool for allocating memory is automatically created in each nginx shared
1621 memory in that zone. 1675 zone.
1622 The pool is located in the beginning of the shared zone and can be accessed by 1676 The pool is located in the beginning of the shared zone and can be accessed by
1623 the expression <literal>(ngx_slab_pool_t *) shm_zone->shm.addr</literal>. 1677 the expression <literal>(ngx_slab_pool_t *) shm_zone->shm.addr</literal>.
1624 Allocation in shared zone is done by calling one of the functions 1678 To allocate memory in a shared zone, call either
1625 <literal>ngx_slab_alloc(pool, size)/ngx_slab_calloc(pool, size)</literal>. 1679 <literal>ngx_slab_alloc(pool, size)</literal> or
1626 Memory is freed by calling <literal>ngx_slab_free(pool, p)</literal>. 1680 <literal>ngx_slab_calloc(pool, size)</literal>.
1681 To free memory, call <literal>ngx_slab_free(pool, p)</literal>.
1627 </para> 1682 </para>
1628 1683
1629 <para> 1684 <para>
1630 Slab pool divides all shared zone into pages. 1685 Slab pool divides all shared zone into pages.
1631 Each page is used for allocating objects of the same size. 1686 Each page is used for allocating objects of the same size.
1632 Only the sizes which are powers of 2, and not less than 8, are considered. 1687 The specified size must be a power of 2, and greater than the minimum size of
1633 Other sizes are rounded up to one of these values. 1688 8 bytes.
1634 For each page, a bitmask is kept, showing which blocks within that page are in 1689 Nonconforming values are rounded up.
1635 use and which are free for allocation. 1690 A bitmask for each page tracks which blocks are in use and which are free for
1636 For sizes greater than half-page (usually, 2048 bytes), allocation is done by 1691 allocation.
1637 entire pages. 1692 For sizes greater than a half page (which is usually 2048 bytes), allocation is
1638 </para> 1693 done an entire page at a time
1639 1694 </para>
1640 <para> 1695
1641 To protect data in shared memory from concurrent access, mutex is available in 1696 <para>
1642 the <literal>mutex</literal> field of <literal>ngx_slab_pool_t</literal>. 1697 To protect data in shared memory from concurrent access, use the mutex
1643 The mutex is used by the slab pool while allocating and freeing memory. 1698 available in the <literal>mutex</literal> field of
1644 However, it can be used to protect any other user data structures, 1699 <literal>ngx_slab_pool_t</literal>.
1645 allocated in the shared zone. 1700 A mutex is most commonly used by the slab pool while allocating and freeing
1646 Locking is done by calling 1701 memory, but it can be used to protect any other user data structures allocated
1647 <literal>ngx_shmtx_lock(&amp;shpool->mutex)</literal>, unlocking is done by 1702 in the shared zone.
1648 calling <literal>ngx_shmtx_unlock(&amp;shpool->mutex)</literal>. 1703 To lock or unlock a mutex, call
1704 <literal>ngx_shmtx_lock(&amp;shpool->mutex)</literal> or
1705 <literal>ngx_shmtx_unlock(&amp;shpool->mutex)</literal> respectively.
1649 </para> 1706 </para>
1650 1707
1651 1708
1652 <programlisting> 1709 <programlisting>
1653 ngx_str_t name; 1710 ngx_str_t name;
1660 ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t)); 1717 ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t));
1661 if (ctx == NULL) { 1718 if (ctx == NULL) {
1662 /* error */ 1719 /* error */
1663 } 1720 }
1664 1721
1665 /* add an entry for 65k shared zone */ 1722 /* add an entry for 64k shared zone */
1666 shm_zone = ngx_shared_memory_add(cf, &amp;name, 65536, &amp;ngx_foo_module); 1723 shm_zone = ngx_shared_memory_add(cf, &amp;name, 65536, &amp;ngx_foo_module);
1667 if (shm_zone == NULL) { 1724 if (shm_zone == NULL) {
1668 /* error */ 1725 /* error */
1669 } 1726 }
1670 1727
1721 1778
1722 1779
1723 <section name="Logging" id="logging"> 1780 <section name="Logging" id="logging">
1724 1781
1725 <para> 1782 <para>
1726 For logging nginx code uses <literal>ngx_log_t</literal> objects. 1783 For logging nginx uses <literal>ngx_log_t</literal> objects.
1727 Nginx logger provides support for several types of output: 1784 The nginx logger supports several types of output:
1728 1785
1729 <list type="bullet"> 1786 <list type="bullet">
1730 1787
1731 <listitem> 1788 <listitem>
1732 stderr — logging to standard error output 1789 stderr — Logging to standard error (stderr)
1733 </listitem> 1790 </listitem>
1734 1791
1735 <listitem> 1792 <listitem>
1736 file — logging to file 1793 file — Logging to a file
1737 </listitem> 1794 </listitem>
1738 1795
1739 <listitem> 1796 <listitem>
1740 syslog — logging to syslog 1797 syslog — Logging to syslog
1741 </listitem> 1798 </listitem>
1742 1799
1743 <listitem> 1800 <listitem>
1744 memory — logging to internal memory storage for development purposes. 1801 memory — Logging to internal memory storage for development purposes; the memory
1745 The memory could be accessed later with debugger 1802 can be accessed later with a debugger
1746 </listitem> 1803 </listitem>
1747 1804
1748 </list> 1805 </list>
1749 </para> 1806 </para>
1750 1807
1751 <para> 1808 <para>
1752 A logger instance may actually be a chain of loggers, linked to each other with 1809 A logger instance can be a chain of loggers, linked to each other with
1753 the <literal>next</literal> field. 1810 the <literal>next</literal> field.
1754 Each message is written to all loggers in chain. 1811 In this case, each message is written to all loggers in the chain.
1755 </para> 1812 </para>
1756 1813
1757 <para> 1814 <para>
1758 Each logger has an error level which limits the messages written to that log. 1815 For each logger, a severity level controls which messages are written to the
1759 The following error levels are supported by nginx: 1816 log (only events assigned that level or higher are logged).
1817 The following severity levels are supported:
1760 </para> 1818 </para>
1761 1819
1762 <para> 1820 <para>
1763 <list type="bullet"> 1821 <list type="bullet">
1764 1822
1796 1854
1797 </list> 1855 </list>
1798 </para> 1856 </para>
1799 1857
1800 <para> 1858 <para>
1801 For debug logging, debug mask is checked as well. The following debug masks 1859 For debug logging, the debug mask is checked as well.
1802 exist: 1860 The debug masks are:
1803 </para> 1861 </para>
1804 1862
1805 <para> 1863 <para>
1806 <list type="bullet"> 1864 <list type="bullet">
1807 1865
1848 1906
1849 <para> 1907 <para>
1850 <list type="bullet"> 1908 <list type="bullet">
1851 1909
1852 <listitem> 1910 <listitem>
1853 <literal>ngx_log_error(level, log, err, fmt, ...)</literal> — error logging 1911 <literal>ngx_log_error(level, log, err, fmt, ...)</literal> — Error logging
1854 </listitem> 1912 </listitem>
1855 1913
1856 <listitem> 1914 <listitem>
1857 <literal>ngx_log_debug0(level, log, err, fmt)</literal>, 1915 <literal>ngx_log_debug0(level, log, err, fmt)</literal>,
1858 <literal>ngx_log_debug1(level, log, err, fmt, arg1)</literal> etc — debug 1916 <literal>ngx_log_debug1(level, log, err, fmt, arg1)</literal> etc — Debug
1859 logging, up to 8 formatting arguments are supported 1917 logging with up to eight supported formatting arguments
1860 </listitem> 1918 </listitem>
1861 1919
1862 </list> 1920 </list>
1863 </para> 1921 </para>
1864 1922
1865 <para> 1923 <para>
1866 A log message is formatted in a buffer of size 1924 A log message is formatted in a buffer of size
1867 <literal>NGX_MAX_ERROR_STR</literal> (currently, 2048 bytes) on stack. 1925 <literal>NGX_MAX_ERROR_STR</literal> (currently, 2048 bytes) on stack.
1868 The message is prepended with error level, process PID, connection id (stored 1926 The message is prepended with the severity level, process ID (PID), connection
1869 in <literal>log->connection</literal>) and system error text. 1927 ID (stored in <literal>log->connection</literal>), and the system error text.
1870 For non-debug messages <literal>log->handler</literal> is called as well to 1928 For non-debug messages <literal>log->handler</literal> is called as well to
1871 prepend more specific information to the log message. 1929 prepend more specific information to the log message.
1872 HTTP module sets <literal>ngx_http_log_error()</literal> function as log 1930 HTTP module sets <literal>ngx_http_log_error()</literal> function as log
1873 handler to log client and server addresses, current action (stored in 1931 handler to log client and server addresses, current action (stored in
1874 <literal>log->action</literal>), client request line, server name etc. 1932 <literal>log->action</literal>), client request line, server name etc.
1875 </para> 1933 </para>
1876 1934
1877 <para>
1878 Example:
1879 </para>
1880
1881
1882 <programlisting> 1935 <programlisting>
1883 /* specify what is currently done */ 1936 /* specify what is currently done */
1884 log->action = "sending mp4 to client”; 1937 log->action = "sending mp4 to client”;
1885 1938
1886 /* error and debug log */ 1939 /* error and debug log */
1890 ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0, 1943 ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0,
1891 "mp4 start:%ui, length:%ui”, mp4->start, mp4->length); 1944 "mp4 start:%ui, length:%ui”, mp4->start, mp4->length);
1892 </programlisting> 1945 </programlisting>
1893 1946
1894 <para> 1947 <para>
1895 Logging result: 1948 The example above results in log entries like these:
1896 </para> 1949 </para>
1897 1950
1898 1951
1899 <programlisting> 1952 <programlisting>
1900 2016/09/16 22:08:52 [info] 17445#0: *1 client prematurely closed connection while 1953 2016/09/16 22:08:52 [info] 17445#0: *1 client prematurely closed connection while
1906 1959
1907 1960
1908 <section name="Cycle" id="cycle"> 1961 <section name="Cycle" id="cycle">
1909 1962
1910 <para> 1963 <para>
1911 Cycle object keeps nginx runtime context, created from a specific 1964 A cycle object stores the nginx runtime context created from a specific
1912 configuration. 1965 configuration.
1913 The type of the cycle is <literal>ngx_cycle_t</literal>. 1966 Its type is <literal>ngx_cycle_t</literal>.
1914 Upon configuration reload a new cycle is created from the new version of nginx 1967 The current cycle is referenced by the <literal>ngx_cycle</literal> global
1915 configuration. 1968 variable and inherited by nginx workers as they start.
1916 The old cycle is usually deleted after a new one is successfully created. 1969 Each time the nginx configuration is reloaded, a new cycle is created from the
1917 Currently active cycle is held in the <literal>ngx_cycle</literal> global 1970 new nginx configuration; the old cycle is usually deleted after the new one is
1918 variable and is inherited by newly started nginx workers. 1971 successfully created.
1919 </para> 1972 </para>
1920 1973
1921 <para> 1974 <para>
1922 A cycle is created by the function <literal>ngx_init_cycle()</literal>. 1975 A cycle is created by the <literal>ngx_init_cycle()</literal> function, which
1923 The function receives the old cycle as the argument. 1976 takes the previous cycle as its argument.
1924 It's used to locate the configuration file and inherit as much resources as 1977 The function locates the previous cycle's configuration file and inherits as
1925 possible from the old cycle to keep nginx running smoothly. 1978 many resources as possible from the previous cycle.
1926 When nginx starts, a fake cycle called “init cycle” is created and is then 1979 A placeholder cycle called "init cycle" is created as nginx start, then is
1927 replaced by a normal cycle, built from configuration. 1980 replaced by an actual cycle built from configuration.
1928 </para> 1981 </para>
1929 1982
1930 <para> 1983 <para>
1931 Some members of the cycle: 1984 Members of the cycle include:
1932 </para> 1985 </para>
1933 1986
1934 <para> 1987 <para>
1935 <list type="bullet"> 1988 <list type="bullet">
1936 1989
1937 <listitem> 1990 <listitem>
1938 <literal>pool</literal> — cycle pool. Created for each new cycle 1991 <literal>pool</literal> — Cycle pool.
1939 </listitem> 1992 Created for each new cycle.
1940 1993 </listitem>
1941 <listitem> 1994
1942 <literal>log</literal> — cycle log. Initially, this log is inherited from the 1995 <listitem>
1943 old cycle. 1996 <literal>log</literal> — Cycle log.
1944 After reading configuration, this member is set to point to 1997 Initially inherited from the old cycle, it is set to point to
1945 <literal>new_log</literal> 1998 <literal>new_log</literal> after the configuration is read.
1946 </listitem> 1999 </listitem>
1947 2000
1948 <listitem> 2001 <listitem>
1949 <literal>new_log</literal> — cycle log, created by the configuration. 2002 <literal>new_log</literal> — Cycle log, created by the configuration.
1950 It's affected by the root scope <literal>error_log</literal> directive 2003 It's affected by the root-scope <literal>error_log</literal> directive.
1951 </listitem> 2004 </listitem>
1952 2005
1953 <listitem> 2006 <listitem>
1954 <literal>connections</literal>, <literal>connection_n</literal> — 2007 <literal>connections</literal>, <literal>connection_n</literal> —
1955 array of connections of type <literal>ngx_connection_t</literal>, created by 2008 Array of connections of type <literal>ngx_connection_t</literal>, created by
1956 the event module while initializing each nginx worker. 2009 the event module while initializing each nginx worker.
1957 The number of connections <literal>connection_n</literal> is set by the 2010 The <literal>worker_connections</literal> directive in the nginx configuration
1958 <literal>worker_connections</literal> directive 2011 sets the number of connections <literal>connection_n</literal>.
1959 </listitem> 2012 </listitem>
1960 2013
1961 <listitem> 2014 <listitem>
1962 <literal>free_connections</literal>, 2015 <literal>free_connections</literal>,
1963 <literal>free_connection_n</literal> — list and number of currently available 2016 <literal>free_connection_n</literal> — List and number of currently available
1964 connections. 2017 connections.
1965 If no connections are available, nginx worker refuses to accept new clients or 2018 If no connections are available, an nginx worker refuses to accept new clients
1966 connect to upstream servers 2019 or connect to upstream servers.
1967 </listitem> 2020 </listitem>
1968 2021
1969 <listitem> 2022 <listitem>
1970 <literal>files</literal>, <literal>files_n</literal> — array for mapping file 2023 <literal>files</literal>, <literal>files_n</literal> — Array for mapping file
1971 descriptors to nginx connections. 2024 descriptors to nginx connections.
1972 This mapping is used by the event modules, having the 2025 This mapping is used by the event modules, having the
1973 <literal>NGX_USE_FD_EVENT</literal> flag (currently, it's poll and devpoll) 2026 <literal>NGX_USE_FD_EVENT</literal> flag (currently, it's
1974 </listitem> 2027 <literal>poll</literal> and <literal>devpoll</literal>).
1975 2028 </listitem>
1976 <listitem> 2029
1977 <literal>conf_ctx</literal> — array of core module configurations. 2030 <listitem>
1978 The configurations are created and filled while reading nginx configuration 2031 <literal>conf_ctx</literal> — Array of core module configurations.
1979 files 2032 The configurations are created and filled during reading of nginx configuration
1980 </listitem> 2033 files.
1981 2034 </listitem>
1982 <listitem> 2035
1983 <literal>modules</literal>, <literal>modules_n</literal> — array of modules 2036 <listitem>
1984 <literal>ngx_module_t</literal>, both static and dynamic, loaded by current 2037 <literal>modules</literal>, <literal>modules_n</literal> — Array of modules
1985 configuration 2038 of type <literal>ngx_module_t</literal>, both static and dynamic, loaded by
1986 </listitem> 2039 the current configuration.
1987 2040 </listitem>
1988 <listitem> 2041
1989 <literal>listening</literal> — array of listening objects 2042 <listitem>
2043 <literal>listening</literal> — Array of listening objects of type
1990 <literal>ngx_listening_t</literal>. 2044 <literal>ngx_listening_t</literal>.
1991 Listening objects are normally added by the the <literal>listen</literal> 2045 Listening objects are normally added by the <literal>listen</literal>
1992 directive of different modules which call the 2046 directive of different modules which call the
1993 <literal>ngx_create_listening()</literal> function. 2047 <literal>ngx_create_listening()</literal> function.
1994 Based on listening objects, listen sockets are created by nginx 2048 Listen sockets are created based on the listening objects.
1995 </listitem> 2049 </listitem>
1996 2050
1997 <listitem> 2051 <listitem>
1998 <literal>paths</literal> — array of paths <literal>ngx_path_t</literal>. 2052 <literal>paths</literal> — Array of paths of type <literal>ngx_path_t</literal>.
1999 Paths are added by calling the function <literal>ngx_add_path()</literal> from 2053 Paths are added by calling the function <literal>ngx_add_path()</literal> from
2000 modules which are going to operate on certain directories. 2054 modules which are going to operate on certain directories.
2001 These directories are created by nginx after reading configuration, if missing. 2055 These directories are created by nginx after reading configuration, if missing.
2002 Moreover, two handlers can be added for each path: 2056 Moreover, two handlers can be added for each path:
2003 2057
2004 <list type="bullet"> 2058 <list type="bullet">
2005 2059
2006 <listitem> 2060 <listitem>
2007 path loader — executed only once in 60 seconds after starting or reloading 2061 path loader — Executes only once in 60 seconds after starting or reloading
2008 nginx. Normally, reads the directory and stores data in nginx shared 2062 nginx.
2009 memory. The handler is called from a dedicated nginx process “nginx 2063 Normally, the loader reads the directory and stores data in nginx shared
2010 cache loader” 2064 memory.
2011 </listitem> 2065 The handler is called from the dedicated nginx process “nginx cache loader”.
2012 2066 </listitem>
2013 <listitem> 2067
2014 path manager — executed periodically. Normally, removes old files from the 2068 <listitem>
2015 directory and reflects these changes in nginx memory. The handler is 2069 path manager — Executes periodically.
2016 called from a dedicated nginx process “nginx cache manager” 2070 Normally, the manager removes old files from the directory and updates nginx
2071 memory to reflect the changes.
2072 The handler is called from the dedicated “nginx cache manager” process.
2017 </listitem> 2073 </listitem>
2018 2074
2019 </list> 2075 </list>
2020 </listitem> 2076 </listitem>
2021 2077
2022 <listitem> 2078 <listitem>
2023 <literal>open_files</literal> — list of <literal>ngx_open_file_t</literal> 2079 <literal>open_files</literal> — List of open file objects of type
2024 objects. 2080 <literal>ngx_open_file_t</literal>, which are created by calling the function
2025 An open file object is created by calling the function
2026 <literal>ngx_conf_open_file()</literal>. 2081 <literal>ngx_conf_open_file()</literal>.
2027 After reading configuration nginx opens all files from the 2082 Currently, nginx uses this kind of open files for logging.
2028 <literal>open_files</literal> list and stores file descriptors in the 2083 After reading the configuration, nginx opens all files in the
2029 <literal>fd</literal> field of each open file object. 2084 <literal>open_files</literal> list and stores each file descriptor in the
2030 The files are opened in append mode and created if missing. 2085 object's <literal>fd</literal> field.
2031 The files from this list are reopened by nginx workers upon receiving the 2086 The files are opened in append mode and are created if missing.
2032 reopen signal (usually it's <literal>USR1</literal>). 2087 The files in the list are reopened by nginx workers upon receiving the
2033 In this case the <literal>fd</literal> fields are changed to new descriptors. 2088 reopen signal (most often <literal>USR1</literal>).
2034 The open files are currently used for logging 2089 In this case the descriptor in the <literal>fd</literal> field is changed to a
2035 </listitem> 2090 new value.
2036 2091 </listitem>
2037 <listitem> 2092
2038 <literal>shared_memory</literal> — list of shared memory zones, each added by 2093 <listitem>
2094 <literal>shared_memory</literal> — List of shared memory zones, each added by
2039 calling the <literal>ngx_shared_memory_add()</literal> function. 2095 calling the <literal>ngx_shared_memory_add()</literal> function.
2040 Shared zones are mapped to the same address range in all nginx processes and 2096 Shared zones are mapped to the same address range in all nginx processes and
2041 are used to share common data, for example HTTP cache in-memory tree 2097 are used to share common data, for example the HTTP cache in-memory tree.
2042 </listitem> 2098 </listitem>
2043 2099
2044 </list> 2100 </list>
2045 </para> 2101 </para>
2046 2102
2051 <para> 2107 <para>
2052 For input/output operations, nginx provides the buffer type 2108 For input/output operations, nginx provides the buffer type
2053 <literal>ngx_buf_t</literal>. 2109 <literal>ngx_buf_t</literal>.
2054 Normally, it's used to hold data to be written to a destination or read from a 2110 Normally, it's used to hold data to be written to a destination or read from a
2055 source. 2111 source.
2056 Buffer can reference data in memory and in file. 2112 A buffer can reference data in memory or in a file and it's technically
2057 Technically it's possible that a buffer references both at the same time. 2113 possible for a buffer to reference both at the same time.
2058 Memory for the buffer is allocated separately and is not related to the buffer 2114 Memory for the buffer is allocated separately and is not related to the buffer
2059 structure <literal>ngx_buf_t</literal>. 2115 structure <literal>ngx_buf_t</literal>.
2060 </para> 2116 </para>
2061 2117
2062 <para> 2118 <para>
2063 The structure <literal>ngx_buf_t</literal> has the following fields: 2119 The <literal>ngx_buf_t</literal> structure has the following fields:
2064 </para> 2120 </para>
2065 2121
2066 <para> 2122 <para>
2067 <list type="bullet"> 2123 <list type="bullet">
2068 2124
2069 <listitem> 2125 <listitem>
2070 <literal>start</literal>, <literal>end</literal> — the boundaries of memory 2126 <literal>start</literal>, <literal>end</literal> — The boundaries of the memory
2071 block, allocated for the buffer 2127 block allocated for the buffer.
2072 </listitem> 2128 </listitem>
2073 2129
2074 <listitem> 2130 <listitem>
2075 <literal>pos</literal>, <literal>last</literal> — memory buffer boundaries, 2131 <literal>pos</literal>, <literal>last</literal> — The boundaries of the memory
2076 normally a subrange of <literal>start</literal> .. <literal>end</literal> 2132 buffer; normally a subrange of <literal>start</literal> ..
2077 </listitem> 2133 <literal>end</literal>.
2078 2134 </listitem>
2079 <listitem> 2135
2080 <literal>file_pos</literal>, <literal>file_last</literal> — file buffer 2136 <listitem>
2081 boundaries, these are offsets from the beginning of the file 2137 <literal>file_pos</literal>, <literal>file_last</literal> — The boundaries of a
2082 </listitem> 2138 file buffer, expressed as offsets from the beginning of the file.
2083 2139 </listitem>
2084 <listitem> 2140
2085 <literal>tag</literal> — unique value, used to distinguish buffers, created by 2141 <listitem>
2086 different nginx module, usually, for the purpose of buffer reuse 2142 <literal>tag</literal> — Unique value used to distinguish buffers; created by
2087 </listitem> 2143 different nginx modules, usually for the purpose of buffer reuse.
2088 2144 </listitem>
2089 <listitem> 2145
2090 <literal>file</literal> — file object 2146 <listitem>
2091 </listitem> 2147 <literal>file</literal> — File object.
2092 2148 </listitem>
2093 <listitem> 2149
2094 <literal>temporary</literal> — flag, meaning that the buffer references 2150 <listitem>
2095 writable memory 2151 <literal>temporary</literal> — Flag indicating that the buffer references
2096 </listitem> 2152 writable memory.
2097 2153 </listitem>
2098 <listitem> 2154
2099 <literal>memory</literal> — flag, meaning that the buffer references read-only 2155 <listitem>
2100 memory 2156 <literal>memory</literal> — Flag indicating that the buffer references read-only
2101 </listitem> 2157 memory.
2102 2158 </listitem>
2103 <listitem> 2159
2104 <literal>in_file</literal> — flag, meaning that current buffer references data 2160 <listitem>
2105 in a file 2161 <literal>in_file</literal> — Flag indicating that the buffer references data
2106 </listitem> 2162 in a file.
2107 2163 </listitem>
2108 <listitem> 2164
2109 <literal>flush</literal> — flag, meaning that all data prior to this buffer 2165 <listitem>
2110 should be flushed 2166 <literal>flush</literal> — Flag indicating that all data prior to the buffer
2111 </listitem> 2167 need to be flushed.
2112 2168 </listitem>
2113 <listitem> 2169
2114 <literal>recycled</literal> — flag, meaning that the buffer can be reused and 2170 <listitem>
2115 should be consumed as soon as possible 2171 <literal>recycled</literal> — Flag indicating that the buffer can be reused and
2116 </listitem> 2172 needs to be consumed as soon as possible.
2117 2173 </listitem>
2118 <listitem> 2174
2119 <literal>sync</literal> — flag, meaning that the buffer carries no data or 2175 <listitem>
2176 <literal>sync</literal> — Flag indicating that the buffer carries no data or
2120 special signal like <literal>flush</literal> or <literal>last_buf</literal>. 2177 special signal like <literal>flush</literal> or <literal>last_buf</literal>.
2121 Normally, such buffers are considered an error by nginx. This flags allows 2178 By default nginx considers such buffers an error condition, but this flag tells
2122 skipping the error checks 2179 nginx to skip the error check.
2123 </listitem> 2180 </listitem>
2124 2181
2125 <listitem> 2182 <listitem>
2126 <literal>last_buf</literal> — flag, meaning that current buffer is the last in 2183 <literal>last_buf</literal> — Flag indicating that the buffer is the last in
2127 output 2184 output.
2128 </listitem> 2185 </listitem>
2129 2186
2130 <listitem> 2187 <listitem>
2131 <literal>last_in_chain</literal> — flag, meaning that there's no more data 2188 <literal>last_in_chain</literal> — Flag indicating that there are no more data
2132 buffers in a (sub)request 2189 buffers in a request or subrequest.
2133 </listitem> 2190 </listitem>
2134 2191
2135 <listitem> 2192 <listitem>
2136 <literal>shadow</literal> — reference to another buffer, related to the current 2193 <literal>shadow</literal> — Reference to another ("shadow") buffer related to
2137 buffer. Usually current buffer uses data from the shadow buffer. Once current 2194 the current buffer, usually in the sense that the buffer uses data from the
2138 buffer is consumed, the shadow buffer should normally also be marked as 2195 shadow.
2139 consumed 2196 When the buffer is consumed, the shadow buffer is normally also marked as
2140 </listitem> 2197 consumed.
2141 2198 </listitem>
2142 <listitem> 2199
2143 <literal>last_shadow</literal> — flag, meaning that current buffer is the last 2200 <listitem>
2144 buffer, referencing a particular shadow buffer 2201 <literal>last_shadow</literal> — Flag indicating that the buffer is the last
2145 </listitem> 2202 one that references a particular shadow buffer.
2146 2203 </listitem>
2147 <listitem> 2204
2148 <literal>temp_file</literal> — flag, meaning that the buffer is in a temporary 2205 <listitem>
2149 file 2206 <literal>temp_file</literal> — Flag indicating that the buffer is in a temporary
2207 file.
2150 </listitem> 2208 </listitem>
2151 2209
2152 </list> 2210 </list>
2153 </para> 2211 </para>
2154 2212
2155 <para> 2213 <para>
2156 For input and output buffers are linked in chains. 2214 For input and output operations buffers are linked in chains.
2157 Chain is a sequence of chain links <literal>ngx_chain_t</literal>, defined as 2215 A chain is a sequence of chain links of type <literal>ngx_chain_t</literal>,
2158 follows: 2216 defined as follows:
2159 </para> 2217 </para>
2160 2218
2161 2219
2162 <programlisting> 2220 <programlisting>
2163 typedef struct ngx_chain_s ngx_chain_t; 2221 typedef struct ngx_chain_s ngx_chain_t;
2172 Each chain link keeps a reference to its buffer and a reference to the next 2230 Each chain link keeps a reference to its buffer and a reference to the next
2173 chain link. 2231 chain link.
2174 </para> 2232 </para>
2175 2233
2176 <para> 2234 <para>
2177 Example of using buffers and chains: 2235 An example of using buffers and chains:
2178 </para> 2236 </para>
2179 2237
2180 2238
2181 <programlisting> 2239 <programlisting>
2182 ngx_chain_t * 2240 ngx_chain_t *
2237 --> 2295 -->
2238 2296
2239 <section name="Connection" id="connection"> 2297 <section name="Connection" id="connection">
2240 2298
2241 <para> 2299 <para>
2242 Connection type <literal>ngx_connection_t</literal> is a wrapper around a 2300 The connection type <literal>ngx_connection_t</literal> is a wrapper around a
2243 socket descriptor. Some of the structure fields are: 2301 socket descriptor.
2302 It includes the following fields:
2244 </para> 2303 </para>
2245 2304
2246 <para> 2305 <para>
2247 <list type="bullet"> 2306 <list type="bullet">
2248 2307
2249 <listitem> 2308 <listitem>
2250 <literal>fd</literal> — socket descriptor 2309 <literal>fd</literal> — Socket descriptor
2251 </listitem> 2310 </listitem>
2252 2311
2253 <listitem> 2312 <listitem>
2254 <literal>data</literal> — arbitrary connection context. 2313 <literal>data</literal> — Arbitrary connection context.
2255 Normally, a pointer to a higher level object, built on top of the connection, 2314 Normally, it is a pointer to a higher-level object built on top of the
2256 like HTTP request or Stream session 2315 connection, such as an HTTP request or a Stream session.
2257 </listitem> 2316 </listitem>
2258 2317
2259 <listitem> 2318 <listitem>
2260 <literal>read</literal>, <literal>write</literal> — read and write events for 2319 <literal>read</literal>, <literal>write</literal> — Read and write events for
2261 the connection 2320 the connection.
2262 </listitem> 2321 </listitem>
2263 2322
2264 <listitem> 2323 <listitem>
2265 <literal>recv</literal>, <literal>send</literal>, 2324 <literal>recv</literal>, <literal>send</literal>,
2266 <literal>recv_chain</literal>, <literal>send_chain</literal> — I/O operations 2325 <literal>recv_chain</literal>, <literal>send_chain</literal> — I/O operations
2267 for the connection 2326 for the connection.
2268 </listitem> 2327 </listitem>
2269 2328
2270 <listitem> 2329 <listitem>
2271 <literal>pool</literal> — connection pool 2330 <literal>pool</literal> — Connection pool.
2272 </listitem> 2331 </listitem>
2273 2332
2274 <listitem> 2333 <listitem>
2275 <literal>log</literal> — connection log 2334 <literal>log</literal> — Connection log.
2276 </listitem> 2335 </listitem>
2277 2336
2278 <listitem> 2337 <listitem>
2279 <literal>sockaddr</literal>, <literal>socklen</literal>, 2338 <literal>sockaddr</literal>, <literal>socklen</literal>,
2280 <literal>addr_text</literal> — remote socket address in binary and text forms 2339 <literal>addr_text</literal> — Remote socket address in binary and text forms.
2281 </listitem> 2340 </listitem>
2282 2341
2283 <listitem> 2342 <listitem>
2284 <literal>local_sockaddr</literal>, <literal>local_socklen</literal> — local 2343 <literal>local_sockaddr</literal>, <literal>local_socklen</literal> — Local
2285 socket address in binary form. 2344 socket address in binary form.
2286 Initially, these fields are empty. 2345 Initially, these fields are empty.
2287 Function <literal>ngx_connection_local_sockaddr()</literal> should be used to 2346 Use the <literal>ngx_connection_local_sockaddr()</literal> function to get the
2288 get socket local address 2347 local socket address.
2289 </listitem> 2348 </listitem>
2290 2349
2291 <listitem> 2350 <listitem>
2292 <literal>proxy_protocol_addr</literal>, <literal>proxy_protocol_port</literal> 2351 <literal>proxy_protocol_addr</literal>, <literal>proxy_protocol_port</literal>
2293 - PROXY protocol client address and port, if PROXY protocol is enabled for the 2352 - PROXY protocol client address and port, if the PROXY protocol is enabled for
2294 connection 2353 the connection.
2295 </listitem> 2354 </listitem>
2296 2355
2297 <listitem> 2356 <listitem>
2298 <literal>ssl</literal> — nginx connection SSL context 2357 <literal>ssl</literal> — SSL context for the connection.
2299 </listitem> 2358 </listitem>
2300 2359
2301 <listitem> 2360 <listitem>
2302 <literal>reusable</literal> — flag, meaning, that the connection is at the 2361 <literal>reusable</literal> — Flag indicating the connection is in a state that
2303 state, when it can be reused 2362 makes it eligible for reuse.
2304 </listitem> 2363 </listitem>
2305 2364
2306 <listitem> 2365 <listitem>
2307 <literal>close</literal> — flag, meaning, that the connection is being reused 2366 <literal>close</literal> — Flag indicating that the connection is being reused
2308 and should be closed 2367 and needs to be closed.
2309 </listitem> 2368 </listitem>
2310 2369
2311 </list> 2370 </list>
2312 </para> 2371 </para>
2313 2372
2314 <para> 2373 <para>
2315 An nginx connection can transparently encapsulate SSL layer. 2374 An nginx connection can transparently encapsulate the SSL layer.
2316 In this case the connection <literal>ssl</literal> field holds a pointer to an 2375 In this case the connection's <literal>ssl</literal> field holds a pointer to an
2317 <literal>ngx_ssl_connection_t</literal> structure, keeping all SSL-related data 2376 <literal>ngx_ssl_connection_t</literal> structure, keeping all SSL-related data
2318 for the connection, including <literal>SSL_CTX</literal> and 2377 for the connection, including <literal>SSL_CTX</literal> and
2319 <literal>SSL</literal>. 2378 <literal>SSL</literal>.
2320 The handlers <literal>recv</literal>, <literal>send</literal>, 2379 The <literal>recv</literal>, <literal>send</literal>,
2321 <literal>recv_chain</literal>, <literal>send_chain</literal> are set as well to 2380 <literal>recv_chain</literal>, and <literal>send_chain</literal> handlers are
2322 SSL functions. 2381 set to SSL-enabled functions as well.
2323 </para> 2382 </para>
2324 2383
2325 <para> 2384 <para>
2326 The number of connections per nginx worker is limited by the 2385 The <literal>worker_connections</literal> directive in the nginx configuration
2327 <literal>worker_connections</literal> value. 2386 limits the number of connections per nginx worker.
2328 All connection structures are pre-created when a worker starts and stored in 2387 All connection structures are precreated when a worker starts and stored in
2329 the <literal>connections</literal> field of the cycle object. 2388 the <literal>connections</literal> field of the cycle object.
2330 To reach out for a connection structure, <literal>ngx_get_connection(s, 2389 To retrieve a connection structure, use the
2331 log)</literal> function is used. 2390 <literal>ngx_get_connection(s, log)</literal> function.
2332 The function receives a socket descriptor <literal>s</literal> which needs to 2391 It takes as its <literal>s</literal> argument a socket descriptor, which needs
2333 be wrapped in a connection structure. 2392 to be wrapped in a connection structure.
2334 </para> 2393 </para>
2335 2394
2336 <para> 2395 <para>
2337 Since the number of connections per worker is limited, nginx provides a 2396 Because the number of connections per worker is limited, nginx provides a
2338 way to grab connections which are currently in use. 2397 way to grab connections that are currently in use.
2339 To enable or disable reuse of a connection, function 2398 To enable or disable reuse of a connection, call the
2340 <literal>ngx_reusable_connection(c, reusable)</literal> is called. 2399 <literal>ngx_reusable_connection(c, reusable)</literal> function.
2341 Calling <literal>ngx_reusable_connection(c, 1)</literal> sets the 2400 Calling <literal>ngx_reusable_connection(c, 1)</literal> sets the
2342 <literal>reuse</literal> flag of the connection structure and inserts the 2401 <literal>reuse</literal> flag in the connection structure and inserts the
2343 connection in the <literal>reusable_connections_queue</literal> of the cycle. 2402 connection into the <literal>reusable_connections_queue</literal> of the cycle.
2344 Whenever <literal>ngx_get_connection()</literal> finds out there are no 2403 Whenever <literal>ngx_get_connection()</literal> finds out there are no
2345 available connections in the <literal>free_connections</literal> list of the 2404 available connections in the cycle's <literal>free_connections</literal> list,
2346 cycle, it calls <literal>ngx_drain_connections()</literal> to release a 2405 it calls <literal>ngx_drain_connections()</literal> to release a
2347 specific number of reusable connections. 2406 specific number of reusable connections.
2348 For each such connection, the <literal>close</literal> flag is set and its read 2407 For each such connection, the <literal>close</literal> flag is set and its read
2349 handler is called which is supposed to free the connection by calling 2408 handler is called which is supposed to free the connection by calling
2350 <literal>ngx_close_connection(c)</literal> and make it available for reuse. 2409 <literal>ngx_close_connection(c)</literal> and make it available for reuse.
2351 To exit the state when a connection can be reused 2410 To exit the state when a connection can be reused
2352 <literal>ngx_reusable_connection(c, 0)</literal> is called. 2411 <literal>ngx_reusable_connection(c, 0)</literal> is called.
2353 An example of reusable connections in nginx is HTTP client connections which 2412 HTTP client connections are an example of reusable connections in nginx; they
2354 are marked as reusable until some data is received from the client. 2413 are marked as reusable until the first request byte is received from the client.
2355 </para> 2414 </para>
2356 2415
2357 </section> 2416 </section>
2358 2417
2359 2418
2364 2423
2365 2424
2366 <section name="Event" id="event"> 2425 <section name="Event" id="event">
2367 2426
2368 <para> 2427 <para>
2369 Event object <literal>ngx_event_t</literal> in nginx provides a way to be 2428 Event object <literal>ngx_event_t</literal> in nginx provides a mechanism
2370 notified of a specific event happening. 2429 for notification that a specific event has occurred.
2371 </para> 2430 </para>
2372 2431
2373 <para> 2432 <para>
2374 Some of the fields of the <literal>ngx_event_t</literal> are: 2433 Fields in <literal>ngx_event_t</literal> include:
2375 </para> 2434 </para>
2376 2435
2377 <para> 2436 <para>
2378 <list type="bullet"> 2437 <list type="bullet">
2379 2438
2380 <listitem> 2439 <listitem>
2381 <literal>data</literal> — arbitrary event context, used in event handler, 2440 <literal>data</literal> — Arbitrary event context used in event handlers,
2382 usually, a pointer to a connection, tied with the event 2441 usually as pointer to a connection related to the event.
2383 </listitem> 2442 </listitem>
2384 2443
2385 <listitem> 2444 <listitem>
2386 <literal>handler</literal> — callback function to be invoked when the event 2445 <literal>handler</literal> — Callback function to be invoked when the event
2387 happens 2446 happens.
2388 </listitem> 2447 </listitem>
2389 2448
2390 <listitem> 2449 <listitem>
2391 <literal>write</literal> — flag, meaning that this is the write event. 2450 <literal>write</literal> — Flag indicating a write event.
2392 Used to distinguish between read and write events 2451 Absence of the flag indicates a read event.
2393 </listitem> 2452 </listitem>
2394 2453
2395 <listitem> 2454 <listitem>
2396 <literal>active</literal> — flag, meaning that the event is registered for 2455 <literal>active</literal> — Flag indicating that the event is registered for
2397 receiving I/O notifications, normally from notification mechanisms like epoll, 2456 receiving I/O notifications, normally from notification mechanisms like
2398 kqueue, poll 2457 <literal>epoll</literal>, <literal>kqueue</literal>, <literal>poll</literal>.
2399 </listitem> 2458 </listitem>
2400 2459
2401 <listitem> 2460 <listitem>
2402 <literal>ready</literal> — flag, meaning that the event has received an 2461 <literal>ready</literal> — Flag indicating that the event has received an
2403 I/O notification 2462 I/O notification.
2404 </listitem> 2463 </listitem>
2405 2464
2406 <listitem> 2465 <listitem>
2407 <literal>delayed</literal> — flag, meaning that I/O is delayed due to rate 2466 <literal>delayed</literal> — Flag indicating that I/O is delayed due to rate
2408 limiting 2467 limiting.
2409 </listitem> 2468 </listitem>
2410 2469
2411 <listitem> 2470 <listitem>
2412 <literal>timer</literal> — Red-Black tree node for inserting the event into 2471 <literal>timer</literal> — Red-black tree node for inserting the event into
2413 the timer tree 2472 the timer tree.
2414 </listitem> 2473 </listitem>
2415 2474
2416 <listitem> 2475 <listitem>
2417 <literal>timer_set</literal> — flag, meaning that the event timer is set, 2476 <literal>timer_set</literal> — Flag indicating that the event timer is set and
2418 but not yet expired 2477 not yet expired.
2419 </listitem> 2478 </listitem>
2420 2479
2421 <listitem> 2480 <listitem>
2422 <literal>timedout</literal> — flag, meaning that the event timer has expired 2481 <literal>timedout</literal> — Flag indicating that the event timer has expired.
2423 </listitem> 2482 </listitem>
2424 2483
2425 <listitem> 2484 <listitem>
2426 <literal>eof</literal> — read event flag, meaning that the eof has happened 2485 <literal>eof</literal> — Flag indicating that EOF occurred while reading data.
2427 while reading data 2486 </listitem>
2428 </listitem> 2487
2429 2488 <listitem>
2430 <listitem> 2489 <literal>pending_eof</literal> — Flag indicating that EOF is pending on the
2431 <literal>pending_eof</literal> — flag, meaning that the eof is pending on the
2432 socket, even though there may be some data available before it. 2490 socket, even though there may be some data available before it.
2433 The flag is delivered via <literal>EPOLLRDHUP</literal> epoll event or 2491 The flag is delivered via the <literal>EPOLLRDHUP</literal>
2434 <literal>EV_EOF</literal> kqueue flag 2492 <literal>epoll</literal> event or
2435 </listitem> 2493 <literal>EV_EOF</literal> <literal>kqueue</literal> flag.
2436 2494 </listitem>
2437 <listitem> 2495
2438 <literal>error</literal> — flag, meaning that an error has happened while 2496 <listitem>
2439 reading (for read event) or writing (for write event) 2497 <literal>error</literal> — Flag indicating that an error occurred during
2440 </listitem> 2498 reading (for a read event) or writing (for a write event).
2441 2499 </listitem>
2442 <listitem> 2500
2443 <literal>cancelable</literal> — timer event flag, meaning that the event 2501 <listitem>
2444 handler should be called while performing nginx worker graceful shutdown, event 2502 <literal>cancelable</literal> — Timer event flag, used during graceful shutdown
2445 though event timeout has not yet expired. The flag provides a way to finalize 2503 of nginx workers, to signal that the event handler needs to be called even
2446 certain activities, for example, flush log files 2504 though the event timeout has not yet expired.
2447 </listitem> 2505 The flag provides a way to finalize certain activities, for example flush log
2448 2506 files.
2449 <listitem> 2507 </listitem>
2450 <literal>posted</literal> — flag, meaning that the event is posted to queue 2508
2451 </listitem> 2509 <listitem>
2452 2510 <literal>posted</literal> — Flag indicating that the event is posted to a queue.
2453 <listitem> 2511 </listitem>
2454 <literal>queue</literal> — queue node for posting the event to a queue 2512
2513 <listitem>
2514 <literal>queue</literal> — Queue node for posting the event to a queue.
2455 </listitem> 2515 </listitem>
2456 2516
2457 </list> 2517 </list>
2458 </para> 2518 </para>
2459 2519
2461 2521
2462 2522
2463 <section name="I/O events" id="i_o_events"> 2523 <section name="I/O events" id="i_o_events">
2464 2524
2465 <para> 2525 <para>
2466 Each connection, received with the 2526 Each connection obtained by calling the <literal>ngx_get_connection()</literal>
2467 <literal>ngx_get_connection()</literal> call, has two events attached to it: 2527 function has two attached events, <literal>c->read</literal> and
2468 <literal>c->read</literal> and <literal>c->write</literal>. 2528 <literal>c->write</literal>, which are used for receiving notification that the
2469 These events are used to receive notifications about the socket being ready for 2529 socket is ready for reading or writing.
2470 reading or writing.
2471 All such events operate in Edge-Triggered mode, meaning that they only trigger 2530 All such events operate in Edge-Triggered mode, meaning that they only trigger
2472 notifications when the state of the socket changes. 2531 notifications when the state of the socket changes.
2473 For example, doing a partial read on a socket will not make nginx deliver a 2532 For example, doing a partial read on a socket does not make nginx deliver a
2474 repeated read notification until more data arrive in the socket. 2533 repeated read notification until more data arrives on the socket.
2475 Even when the underlying I/O notification mechanism is essentially 2534 Even when the underlying I/O notification mechanism is essentially
2476 Level-Triggered (poll, select etc), nginx will turn the notifications into 2535 Level-Triggered (<literal>poll</literal>, <literal>select</literal> etc), nginx
2477 Edge-Triggered. 2536 converts the notifications to Edge-Triggered.
2478 To make nginx event notifications consistent across all notifications systems 2537 To make nginx event notifications consistent across all notifications systems
2479 on different platforms, it's required, that the functions 2538 on different platforms, the functions
2480 <literal>ngx_handle_read_event(rev, flags)</literal> and 2539 <literal>ngx_handle_read_event(rev, flags)</literal> and
2481 <literal>ngx_handle_write_event(wev, lowat)</literal> are called after handling 2540 <literal>ngx_handle_write_event(wev, lowat)</literal> must be called after
2482 an I/O socket notification or calling any I/O functions on that socket. 2541 handling an I/O socket notification or calling any I/O functions on that socket.
2483 Normally, these functions are called once in the end of each read or write 2542 Normally, the functions are called once at the end of each read or write
2484 event handler. 2543 event handler.
2485 </para> 2544 </para>
2486 2545
2487 </section> 2546 </section>
2488 2547
2489 2548
2490 <section name="Timer events" id="timer_events"> 2549 <section name="Timer events" id="timer_events">
2491 2550
2492 <para> 2551 <para>
2493 An event can be set to notify a timeout expiration. 2552 An event can be set to send a notification when a timeout expires.
2494 The function <literal>ngx_add_timer(ev, timer)</literal> sets a timeout for an 2553 The function <literal>ngx_add_timer(ev, timer)</literal> sets a timeout for an
2495 event, <literal>ngx_del_timer(ev)</literal> deletes a previously set timeout. 2554 event, <literal>ngx_del_timer(ev)</literal> deletes a previously set timeout.
2496 Timeouts currently set for all existing events, are kept in a global timeout 2555 The global timeout red-black tree <literal>ngx_event_timer_rbtree</literal>
2497 Red-Black tree <literal>ngx_event_timer_rbtree</literal>. 2556 stores all timeouts currently set.
2498 The key in that tree has the type <literal>ngx_msec_t</literal> and is the time 2557 The key in the tree is of type <literal>ngx_msec_t</literal> and is the time
2499 in milliseconds since the beginning of January 1, 1970 (modulus 2558 when the event expires, expressed in milliseconds since the midnight on of
2500 <literal>ngx_msec_t</literal> max value) at which the event should expire. 2559 January 1, 1970 modulus <literal>ngx_msec_t</literal> max value.
2501 The tree structure provides fast inserting and deleting operations, as well as 2560 The tree structure enables fast insertion and deletion operations, as well as
2502 accessing the nearest timeouts. 2561 access to the nearest timeouts, which nginx uses to find out how long to wait
2503 The latter is used by nginx to find out for how long to wait for I/O events 2562 for I/O events and for expiring timeout events.
2504 and for expiring timeout events afterwards.
2505 </para> 2563 </para>
2506 2564
2507 </section> 2565 </section>
2508 2566
2509 2567
2513 An event can be posted which means that its handler will be called at some 2571 An event can be posted which means that its handler will be called at some
2514 point later within the current event loop iteration. 2572 point later within the current event loop iteration.
2515 Posting events is a good practice for simplifying code and escaping stack 2573 Posting events is a good practice for simplifying code and escaping stack
2516 overflows. 2574 overflows.
2517 Posted events are held in a post queue. 2575 Posted events are held in a post queue.
2518 The macro <literal>ngx_post_event(ev, q)</literal> posts the event 2576 The <literal>ngx_post_event(ev, q)</literal> mscro posts the event
2519 <literal>ev</literal> to the post queue <literal>q</literal>. 2577 <literal>ev</literal> to the post queue <literal>q</literal>.
2520 Macro <literal>ngx_delete_posted_event(ev)</literal> deletes the event 2578 The <literal>ngx_delete_posted_event(ev)</literal> macro deletes the event
2521 <literal>ev</literal> from whatever queue it's currently posted. 2579 <literal>ev</literal> from the queue it's currently posted in.
2522 Normally, events are posted to the <literal>ngx_posted_events</literal> queue. 2580 Normally, events are posted to the <literal>ngx_posted_events</literal> queue,
2523 This queue is processed late in the event loop — after all I/O and timer 2581 which is processed late in the event loop — after all I/O and timer
2524 events are already handled. 2582 events are already handled.
2525 The function <literal>ngx_event_process_posted()</literal> is called to process 2583 The function <literal>ngx_event_process_posted()</literal> is called to process
2526 an event queue. 2584 an event queue.
2527 This function calls event handlers until the queue is not empty. This means 2585 It calls event handlers until the queue is not empty.
2528 that a posted event handler can post more events to be processed within the 2586 This means that a posted event handler can post more events to be processed
2529 current event loop iteration. 2587 within the current event loop iteration.
2530 </para> 2588 </para>
2531 2589
2532 <para> 2590 <para>
2533 Example: 2591 An example:
2534 </para> 2592 </para>
2535 2593
2536 2594
2537 <programlisting> 2595 <programlisting>
2538 void 2596 void
2581 2639
2582 2640
2583 <section name="Event loop" id="event_loop"> 2641 <section name="Event loop" id="event_loop">
2584 2642
2585 <para> 2643 <para>
2586 All nginx processes which do I/O, have an event loop. 2644 Except for the nginx master process, all nginx processes do I/O and so have an
2587 The only type of process which does not have I/O, is nginx master process which 2645 event loop.
2588 spends most of its time in <literal>sigsuspend()</literal> call waiting for 2646 (The nginx master process instead spends most of its time in the
2589 signals to arrive. 2647 <literal>sigsuspend()</literal> call waiting for signals to arrive.)
2590 Event loop is implemented in <literal>ngx_process_events_and_timers()</literal> 2648 The nginx event loop is implemented in the
2591 function. 2649 <literal>ngx_process_events_and_timers()</literal> function, which is called
2592 This function is called repeatedly until the process exits. 2650 repeatedly until the process exits.
2593 It has the following stages: 2651 </para>
2594 </para> 2652
2595 2653 <para>
2596 <para> 2654 The event loop has the following stages:
2655
2597 <list type="bullet"> 2656 <list type="bullet">
2598 2657
2599 <listitem> 2658 <listitem>
2600 find nearest timeout by calling <literal>ngx_event_find_timer()</literal>. 2659 Find the timeout that is closest to expiring, by calling
2601 This function finds the leftmost timer tree node and returns the number of 2660 <literal>ngx_event_find_timer()</literal>.
2602 milliseconds until that node expires 2661 This function finds the leftmost node in the timer tree and returns the
2603 </listitem> 2662 number of milliseconds until the node expires.
2604 2663 </listitem>
2605 <listitem> 2664
2606 process I/O events by calling a handler, specific to event notification 2665 <listitem>
2666 Process I/O events by calling a handler, specific to the event notification
2607 mechanism, chosen by nginx configuration. 2667 mechanism, chosen by nginx configuration.
2608 This handler waits for at least one I/O event to happen, but no longer, than 2668 This handler waits for at least one I/O event to happen, but only until the next
2609 the nearest timeout. 2669 timeout expires.
2610 For each read or write event which has happened, the <literal>ready</literal> 2670 When a read or write event occurs, the <literal>ready</literal>
2611 flag is set and its handler is called. 2671 flag is set and the event's handler is called.
2612 For Linux, normally, the <literal>ngx_epoll_process_events()</literal> handler 2672 For Linux, the <literal>ngx_epoll_process_events()</literal> handler
2613 is used which calls <literal>epoll_wait()</literal> to wait for I/O events 2673 is normally used, which calls <literal>epoll_wait()</literal> to wait for I/O
2614 </listitem> 2674 events.
2615 2675 </listitem>
2616 <listitem> 2676
2617 expire timers by calling <literal>ngx_event_expire_timers()</literal>. 2677 <listitem>
2618 The timer tree is iterated from the leftmost element to the right until a not 2678 Expire timers by calling <literal>ngx_event_expire_timers()</literal>.
2619 yet expired timeout is found. 2679 The timer tree is iterated from the leftmost element to the right until an
2680 unexpired timeout is found.
2620 For each expired node the <literal>timedout</literal> event flag is set, 2681 For each expired node the <literal>timedout</literal> event flag is set,
2621 <literal>timer_set</literal> flag is reset, and the event handler is called 2682 the <literal>timer_set</literal> flag is reset, and the event handler is called
2622 </listitem> 2683 </listitem>
2623 2684
2624 <listitem> 2685 <listitem>
2625 process posted events by calling <literal>ngx_event_process_posted()</literal>. 2686 Process posted events by calling <literal>ngx_event_process_posted()</literal>.
2626 The function repeatedly removes the first element from the posted events 2687 The function repeatedly removes the first element from the posted events
2627 queue and calls its handler until the queue gets empty 2688 queue and calls the element's handler, until the queue is empty.
2628 </listitem> 2689 </listitem>
2629 2690
2630 </list> 2691 </list>
2631 </para> 2692 </para>
2632 2693
4056 It stores global settings for a module 4117 It stores global settings for a module
4057 </listitem> 4118 </listitem>
4058 4119
4059 <listitem> 4120 <listitem>
4060 Server configuration. 4121 Server configuration.
4061 This configuraion applies to a single nginx server{}. 4122 This configuration applies to a single nginx server{}.
4062 It stores server-specific settings for a module 4123 It stores server-specific settings for a module
4063 </listitem> 4124 </listitem>
4064 4125
4065 <listitem> 4126 <listitem>
4066 Location configuration. 4127 Location configuration.
4067 This configuraion applies to a single location{}, if{} or limit_except() block. 4128 This configuration applies to a single location{}, if{} or limit_except() block.
4068 This configuration stores settings specific to a location 4129 This configuration stores settings specific to a location
4069 </listitem> 4130 </listitem>
4070 4131
4071 </list> 4132 </list>
4072 4133
4297 </listitem> 4358 </listitem>
4298 4359
4299 <listitem> 4360 <listitem>
4300 <literal>NGX_HTTP_REWRITE_PHASE</literal> — same as 4361 <literal>NGX_HTTP_REWRITE_PHASE</literal> — same as
4301 <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal>, but for a new location, 4362 <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal>, but for a new location,
4302 chosen at the prevous phase 4363 chosen at the previous phase
4303 </listitem> 4364 </listitem>
4304 4365
4305 <listitem> 4366 <listitem>
4306 <literal>NGX_HTTP_POST_REWRITE_PHASE</literal> — a special phase, used to 4367 <literal>NGX_HTTP_POST_REWRITE_PHASE</literal> — a special phase, used to
4307 redirect the request to a new location, if the URI was changed during rewrite. 4368 redirect the request to a new location, if the URI was changed during rewrite.
4609 is used. 4670 is used.
4610 It takes configuration (where variable is registered), variable name and 4671 It takes configuration (where variable is registered), variable name and
4611 flags that control its behaviour: 4672 flags that control its behaviour:
4612 4673
4613 <list type="bullet"> 4674 <list type="bullet">
4614 <listitem><literal>NGX_HTTP_VAR_CHANGEABLE</literal>  — allows redefining 4675 <listitem><literal>NGX_HTTP_VAR_CHANGEABLE</literal> — allows redefining
4615 the variable; If another module will define a variable with such name, 4676 the variable; If another module will define a variable with such name,
4616 no conflict will happen. 4677 no conflict will happen.
4617 For example, this allows user to override variables using the 4678 For example, this allows user to override variables using the
4618 <link doc="../http/ngx_http_rewrite_module.xml" id="set"/> directive. 4679 <link doc="../http/ngx_http_rewrite_module.xml" id="set"/> directive.
4619 </listitem> 4680 </listitem>
4620 4681
4621 <listitem><literal>NGX_HTTP_VAR_NOCACHEABLE</literal>  — disables caching, 4682 <listitem><literal>NGX_HTTP_VAR_NOCACHEABLE</literal> — disables caching,
4622 is useful for such variables as <literal>$time_local</literal> 4683 is useful for such variables as <literal>$time_local</literal>
4623 </listitem> 4684 </listitem>
4624 4685
4625 <listitem><literal>NGX_HTTP_VAR_NOHASH</literal>  — indicates that 4686 <listitem><literal>NGX_HTTP_VAR_NOHASH</literal> — indicates that
4626 this variable is only accessible by index, not by name. 4687 this variable is only accessible by index, not by name.
4627 This is a small optimization which may be used when it is known that the 4688 This is a small optimization which may be used when it is known that the
4628 variable is not needed in modules like SSI or Perl. 4689 variable is not needed in modules like SSI or Perl.
4629 </listitem> 4690 </listitem>
4630 4691
4631 <listitem><literal>NGX_HTTP_VAR_PREFIX</literal>  — the name of this 4692 <listitem><literal>NGX_HTTP_VAR_PREFIX</literal> — the name of this
4632 variable is a prefix. 4693 variable is a prefix.
4633 A handler must implement additional logic to obtain value of specific 4694 A handler must implement additional logic to obtain value of specific
4634 variable. 4695 variable.
4635 For example, all “<literal>arg_</literal>” variables are processed by the 4696 For example, all “<literal>arg_</literal>” variables are processed by the
4636 same handler which performs lookup in request arguments and returns value 4697 same handler which performs lookup in request arguments and returns value
4936 </programlisting> 4997 </programlisting>
4937 4998
4938 <para> 4999 <para>
4939 The function <literal>ngx_http_named_location(r, name)</literal> redirects 5000 The function <literal>ngx_http_named_location(r, name)</literal> redirects
4940 a request to a named location. The name of the location is passed as the 5001 a request to a named location. The name of the location is passed as the
4941 argument. The location is looked up among all named locations of the current 5002 argument.
5003 The location is looked up among all named locations of the current
4942 server, after which the requests switches to the 5004 server, after which the requests switches to the
4943 <literal>NGX_HTTP_REWRITE_PHASE</literal> phase. 5005 <literal>NGX_HTTP_REWRITE_PHASE</literal> phase.
4944 </para> 5006 </para>
4945 5007
4946 <para> 5008 <para>
4961 5023
4962 <para> 5024 <para>
4963 Both functions <literal>ngx_http_internal_redirect(r, uri, args)</literal> 5025 Both functions <literal>ngx_http_internal_redirect(r, uri, args)</literal>
4964 and <literal>ngx_http_named_location(r, name)</literal> may be called when 5026 and <literal>ngx_http_named_location(r, name)</literal> may be called when
4965 a request already has some contexts saved in its <literal>ctx</literal> field 5027 a request already has some contexts saved in its <literal>ctx</literal> field
4966 by nginx modules. These contexts could become inconsistent with the new 5028 by nginx modules.
4967 location configuration. To prevent inconsistency, all request contexts are 5029 These contexts could become inconsistent with the new
5030 location configuration.
5031 To prevent inconsistency, all request contexts are
4968 erased by both redirect functions. 5032 erased by both redirect functions.
4969 </para> 5033 </para>
4970 5034
4971 <para> 5035 <para>
4972 Redirected and rewritten requests become internal and may access the 5036 Redirected and rewritten requests become internal and may access the
4973 <link doc="../http/ngx_http_core_module.xml" id="internal">internal</link> 5037 <link doc="../http/ngx_http_core_module.xml" id="internal">internal</link>
4974 locations. Internal requests have the <literal>internal</literal> flag set. 5038 locations.
5039 Internal requests have the <literal>internal</literal> flag set.
4975 </para> 5040 </para>
4976 5041
4977 </section> 5042 </section>
4978 5043
4979 5044