-For getting the last system error code, the ngx_errno macro -is available. +The ngx_errno macro returns the last system error code. It's mapped to errno on POSIX platforms and to GetLastError() call in Windows. -For getting the last socket error number, the -ngx_socket_errno macro is available. -It's mapped to errno on POSIX systems as well, -and to WSAGetLastError() call on Windows. -For performance reasons the values of ngx_errno or -ngx_socket_errno should not be accessed more than -once in a row. -The error value should be stored in a local variable of type -ngx_err_t for using multiple times, if required. -For setting errors, ngx_set_errno(errno) and -ngx_set_socket_errno(errno) macros are available. - - - -The values of ngx_errno or -ngx_socket_errno can be passed to logging functions +The ngx_socket_errno macro returns the last socket error +number. +Like the ngx_errno macro, it's mapped to +errno on POSIX platforms. +It's mapped to the WSAGetLastError() call on Windows. +Accessing the values of ngx_errno or +ngx_socket_errno more than once in a row can cause +performance issues. +If the error value might be used multiple times, store it in a local variable +of type ngx_err_t. +To set errors, use the ngx_set_errno(errno) and +ngx_set_socket_errno(errno) macros. + + + +The values of ngx_errno and +ngx_socket_errno can be passed to the logging functions ngx_log_error() and ngx_log_debugX(), in which case system error text is added to the log message. @@ -264,7 +261,7 @@

-For C strings, nginx code uses unsigned character type pointer +For C strings, nginx uses the unsigned character type pointer u_char *. @@ -281,20 +278,20 @@ -The len field holds the string length, +The len field holds the string length and data holds the string data. The string, held in ngx_str_t, may or may not be null-terminated after the len bytes. In most cases it’s not. -However, in certain parts of code (for example, when parsing configuration), -ngx_str_t objects are known to be null-terminated, and that -knowledge is used to simplify string comparison and makes it easier to pass -those strings to syscalls. - - - -A number of string operations are provided in nginx. -They are declared in src/core/ngx_string.h. +However, in certain parts of the code (for example, when parsing configuration), +ngx_str_t objects are known to be null-terminated, which +simplifies string comparison and makes it easier to pass the strings to +syscalls. + + + +The string operations in nginx are declared in +src/core/ngx_string.h Some of them are wrappers around standard C functions: @@ -342,36 +339,36 @@ -Some nginx-specific string functions: +Other string functions are nginx-specific -ngx_memzero() fills memory with zeroes - - - -ngx_cpymem() does the same as +ngx_memzero() — Fills memory with zeroes. + + + +ngx_cpymem() — Does the same as ngx_memcpy(), but returns the final destination address -This one is handy for appending multiple strings in a row - - - -ngx_movemem() does the same as +This one is handy for appending multiple strings in a row. + + + +ngx_movemem() — Does the same as ngx_memmove(), but returns the final destination address. -ngx_strlchr() searches for a character in a string, -delimited by two pointers +ngx_strlchr() — Searches for a character in a string, +delimited by two pointers. -Some case conversion and comparison functions: +The following functions perform case conversion and comparison: @@ -406,7 +403,7 @@

-A number of formatting functions are provided by nginx. These functions support nginx-specific types: +The following formatting functions support nginx-specific types: @@ -437,28 +434,55 @@ -The full list of formatting options, supported by these functions, can be found +The full list of formatting options, supported by these functions is in src/core/ngx_string.c. Some of them are: - -%O — off_t -%T — time_t -%z — size_t -%i — ngx_int_t -%p — void * -%V — ngx_str_t * -%s — u_char * (null-terminated) -%*s — size_t + u_char * - - - -The ‘u’ modifier makes most types unsigned, ‘X’/‘x’ convert output to hex. - - - -Example: + + + +%O — off_t + + + +%T — time_t + + + +%z — size_t + + + +%i — ngx_int_t_t + + + +%p — void * + + + +%V — ngx_str_t * + + + +%s — u_char * (null-terminated) + + + +%*s — size_t + u_char * + + + + + + +You can prepend u on most types to make them unsigned. +To convert output to hex, use X or x. + + + +For example: u_char buf[NGX_INT_T_LEN]; @@ -478,48 +502,53 @@

-Several functions for numeric conversion are implemented in nginx: - - - +Several functions for numeric conversion are implemented in nginx. +The first four each convert a string of given length to a positive integer of +the indicated type. +They return NGX_ERROR on error. + -ngx_atoi(line, n) — converts a string of given length to a -positive integer of type ngx_int_t. -Returns NGX_ERROR on error - - - -ngx_atosz(line, n) — same for ssize_t -type - - - -ngx_atoof(line, n) — same for off_t -type - - - -ngx_atotm(line, n) — same for time_t -type - - - -ngx_atofp(line, n, point) — converts a fixed point floating +ngx_atoi(line, n) — ngx_int_t + + + +ngx_atosz(line, n) — ssize_t + + + +ngx_atoof(line, n) — off_t + + + +ngx_atotm(line, n) — time_t + + + + + + +There are two additional numeric conversion functions. +Like the first four, they return NGX_ERROR on error. + + + + +ngx_atofp(line, n, point) — Converts a fixed point floating number of given length to a positive integer of type ngx_int_t. -The result is shifted left by points decimal -positions. The string representation of the number is expected to have no more +The result is shifted left by point decimal +positions. +The string representation of the number is expected to have no more than points fractional digits. -Returns NGX_ERROR on error. For example, -ngx_atofp("10.5", 4, 2) returns 1050 - - - -ngx_hextoi(line, n) — converts hexadecimal representation of -a positive integer to ngx_int_t. Returns -NGX_ERROR on error +For example, ngx_atofp("10.5", 4, 2) returns +1050. + + + +ngx_hextoi(line, n) — Converts a hexadecimal representation +of a positive integer to ngx_int_t. @@ -537,10 +566,11 @@ -To use a regular expression for string matching, first, it needs to be -compiled, this is usually done at configuration phase. +To use a regular expression for string matching, it first needs to be +compiled, which is usually done at the configuration phase. Note that since PCRE support is optional, all code using the interface must be protected by the surrounding NGX_PCRE macro: + #if (NGX_PCRE) ngx_regex_t *re; @@ -566,14 +596,14 @@ re = rc.regex; #endif -After successful compilation, ngx_regex_compile_t structure -fields captures and named_captures -are filled with count of all and named captures respectively found in the -regular expression. - - - -Later, the compiled regular expression may be used to match strings against it: +After successful compilation, the captures and +named_captures fields in the +ngx_regex_compile_t structure contain the count of all +captures and named captures, respectively, found in the regular expression. + + + +The compiled regular expression can then be used for matching against strings: ngx_int_t n; int captures[(1 + rc.captures) * 3]; @@ -592,19 +622,19 @@ ngx_log_error(NGX_LOG_ALERT, log, 0, ngx_regex_exec_n " failed: %i", n); } -The arguments of ngx_regex_exec() are: the compiled regular -expression re, string to match s, -optional array of integers to hold found captures -and its size. -The captures array size must be a multiple of three, -per requirements of the +The arguments to ngx_regex_exec() are the compiled regular +expression re, the string to match s, +an optional array of integers to hold any captures that are +found, and the array's size. +The size of the captures array must be a multiple of three, +as required by the PCRE API. -In the example, its size is calculated from a total number of captures plus -one for the matched string itself. - - - -Now, if there are matches, captures may be accessed: +In the example, the size is calculated from the total number of captures plus +1one for the matched string itself. + + + +If there are matches, captures can be accessed as follows: u_char *p; size_t size; @@ -639,10 +669,10 @@ The ngx_regex_exec_array() function accepts the array of ngx_regex_elt_t elements (which are just compiled regular -expressions with associated names), a string to match and a log. -The function will apply expressions from the array to the string until -the match is found or no more expressions are left. -The return value is NGX_OK in case of match and +expressions with associated names), a string to match, and a log. +The function applies expressions from the array to the string until +either a match is found or no more expressions are left. +The return value is NGX_OK when there is a match and NGX_DECLINED otherwise, or NGX_ERROR in case of error. @@ -655,8 +685,8 @@

-The ngx_time_t structure represents time split into seconds -and milliseconds with specification of GMT offset: +The ngx_time_t structure represents time with three separate +types for seconds, milliseconds, and the GMT offset: typedef struct { time_t sec; @@ -664,46 +694,49 @@ ngx_int_t gmtoff; } ngx_time_t; -The ngx_tm_t is an alias for struct tm -on UNIX platforms and SYSTEMTIME on Windows. - - - -To obtain current time, usually it is enough to access one of available global -variables, representing the cached time value in desired format. -The ngx_current_msec variable holds milliseconds elapsed -since Epoch and truncated to ngx_msec_t. - - - -Available string representations are: +The ngx_tm_t structure is an alias for +struct tm on UNIX platforms and SYSTEMTIME +on Windows. + + + +To obtain the current time, it is usually sufficient to access one of the +available global variables, representing the cached time value in the desired +format. +For example, the ngx_current_msec variable holds the number +of milliseconds elapsed since Epoch and truncated to +ngx_msec_t. + + + +The available string representations are: -ngx_cached_err_log_time — used in error log: -"1970/09/28 12:00:00" - - - -ngx_cached_http_log_time — used in HTTP access log: -"28/Sep/1970:12:00:00 +0600" - - - -ngx_cached_syslog_time — used in syslog: -"Sep 28 12:00:00" - - - -ngx_cached_http_time — used in HTTP for headers: -"Mon, 28 Sep 1970 06:00:00 GMT" - - - -ngx_cached_http_log_iso8601 — in the ISO 8601 +ngx_cached_err_log_time — Used in error log entries: +"1970/09/28 12:00:00" + + + +ngx_cached_http_log_time — Used in HTTP access log entries: +"28/Sep/1970:12:00:00 +0600" + + + +ngx_cached_syslog_time — Used in syslog entries: +"Sep 28 12:00:00" + + + +ngx_cached_http_time — Used in HTTP headers: +"Mon, 28 Sep 1970 06:00:00 GMT" + + + +ngx_cached_http_log_iso8601 — The ISO 8601 standard format: -"1970-09-28T12:00:00+06:00" +"1970-09-28T12:00:00+06:00" @@ -711,44 +744,47 @@ The ngx_time() and ngx_timeofday() macros -returning current value of seconds are a preferred way to access cached -time value. - - - -To obtain the time explicitly, ngx_gettimeofday() may -be used, which updates its argument (pointer to +return the current time value in seconds and are the preferred way to access +the cached time value. + + + +To obtain the time explicitly, use ngx_gettimeofday(), +which updates its argument (pointer to struct timeval). -Time is always updated when nginx returns to event loop from system calls. +The time is always updated when nginx returns to the event loop from system +calls. To update the time immediately, call ngx_time_update(), -or ngx_time_sigsafe_update() if you need it in the +or ngx_time_sigsafe_update() if updating the time in the signal handler context. -The following functions convert time_t into broken-down time -representation, either ngx_tm_t or -struct tm for those with libc prefix: +The following functions convert time_t into the indicated +broken-down time representation. +The first function in each pair converts time_t to +ngx_tm_t and the second (with the _libc_ +infix) to struct tm: -ngx_gmtime(), ngx_libc_gmtime() — result time is UTC - - - -ngx_localtime(), ngx_libc_localtime() — result time is -relative to the timezone +ngx_gmtime(), ngx_libc_gmtime() — Time expressed as UTC + + + +ngx_localtime(), ngx_libc_localtime() — Time expressed +relative to the local time zone -The ngx_http_time(buf, time) returns string -representation suitable for use with HTTP headers (for example, -"Mon, 28 Sep 1970 06:00:00 GMT"). -Another possible conversion is provided by -ngx_http_cookie_time(buf, time) that produces format suitable -for HTTP cookies ("Thu, 31-Dec-37 23:55:55 GMT"). +The ngx_http_time(buf, time) function returns a string +representation suitable for use in HTTP headers (for example, +"Mon, 28 Sep 1970 06:00:00 GMT"). +The ngx_http_cookie_time(buf, time) returns a string +representation function returns a string representation suitable +for HTTP cookies ("Thu, 31-Dec-37 23:55:55 GMT").

@@ -775,17 +811,16 @@ -The elements of array are available through the elts field. -The number of elements is held in the nelts field. +The elements of the array are available in the elts field. +The nelts field holds the number of elements. The size field holds the size of a single element and is set -when initializing the array. - - - -An array can be created in a pool with the -ngx_array_create(pool, n, size) call. -An already allocated array object can be initialized with the -ngx_array_init(array, pool, n, size) call. +when the array is initialized. + + + +Use the ngx_array_create(pool, n, size) call to create an +array in a pool, and the ngx_array_init(array, pool, n, size) +call to initialize an array object that has already been allocated. @@ -800,7 +835,7 @@ -Adding elements to array are done with the following functions: +Use the following functions to add elements to an array: @@ -820,9 +855,10 @@ -If currently allocated memory is not enough for new elements, a new memory for -elements is allocated and existing elements are copied to that memory. -The new memory block is normally twice as large, as the existing one. +If the currently allocated amount of memory is not large enough to accommodate +the new elements, a new block of memory is allocated and the existing elements +are copied to it. +The new memory block is normally twice as large as the existing one. @@ -837,8 +873,9 @@

-List in nginx is a sequence of arrays, optimized for inserting a potentially -large number of items. The list type is defined as follows: +In nginx a list is a sequence of arrays, optimized for inserting a potentially +large number of items. +The ngx_list_t list type is defined as follows: @@ -853,7 +890,7 @@ -The actual items are stored in list parts, defined as follows: +The actual items are stored in list parts, which are defined as follows: @@ -868,14 +905,15 @@ -Initially, a list must be initialized by calling +Before use, a list must be initialized by calling ngx_list_init(list, pool, n, size) or created by calling ngx_list_create(pool, n, size). -Both functions receive the size of a single item and a number of items per list -part. -The ngx_list_push(list) function is used to add an item to the -list. Iterating over the items is done by direct accessing the list fields, as -seen in the example: +Both functions take as arguments the size of a single item and a number of +items per list part. +To add an item to a list, use the ngx_list_push(list) +function. +To iterate over the items, directly access the list fields as shown in the +example: @@ -920,17 +958,19 @@ -The primary use for the list in nginx is HTTP input and output headers. - - - -The list does not support item removal. -However, when needed, items can internally be marked as missing without actual -removing from the list. -For example, HTTP output headers which are stored as -ngx_table_elt_t objects, are marked as missing by setting -the hash field of ngx_table_elt_t to -zero. Such items are explicitly skipped, when iterating over the headers. +Lists are primarily used for HTTP input and output headers. + + + +Lists do not support item removal. +However, when needed, items can internally be marked as missing without actually +being removed from the list. +For example, to mark HTTP output headers (which are stored as +ngx_table_elt_t objects) as missing, set the +hash field in ngx_table_elt_t to +zero. +Items marked in this way are explicitly skipped when the headers are iterated +over.

@@ -939,7 +979,7 @@

-Queue in nginx is an intrusive doubly linked list, with each node defined as +In nginx a queue is an intrusive doubly linked list, with each node defined as follows: @@ -954,8 +994,9 @@ -The head queue node is not linked with any data. Before using, the list head -should be initialized with ngx_queue_init(q) call. +The head queue node is not linked with any data. +Use the ngx_queue_init(q) call to initialize the list head +before use. Queues support the following operations: @@ -964,42 +1005,43 @@ ngx_queue_insert_head(h, x), -ngx_queue_insert_tail(h, x) — insert a new node - - - -ngx_queue_remove(x) — remove a queue node - - - -ngx_queue_split(h, q, n) — split a queue at a node, -queue tail is returned in a separate queue - - - -ngx_queue_add(h, n) — add second queue to the first queue +ngx_queue_insert_tail(h, x) — Insert a new node + + + +ngx_queue_remove(x) — Remove a queue node + + + +ngx_queue_split(h, q, n) — Split a queue at a node, +returning the queue tail in a separate queue + + + +ngx_queue_add(h, n) — Add a second queue to the first queue ngx_queue_head(h), -ngx_queue_last(h) — get first or last queue node - - - -ngx_queue_sentinel(h) -- get a queue sentinel object to end iteration at - - - -ngx_queue_data(q, type, link) — get reference to the beginning of a -queue node data structure, considering the queue field offset in it +ngx_queue_last(h) — Get first or last queue node + + + +ngx_queue_sentinel(h) - Get a queue sentinel object to end +iteration at + + + +ngx_queue_data(q, type, link) — Get a reference to the +beginning of a queue node data structure, considering the queue field offset in +it -Example: +An example: @@ -1061,8 +1103,8 @@ To deal with a tree as a whole, you need two nodes: root and sentinel. -Typically, they are added to some custom structure, thus allowing to -organize your data into a tree which leaves contain a link to or embed +Typically, they are added to a custom structure, allowing you to +organize your data into a tree in which the leaves contain a link to or embed your data. @@ -1078,11 +1120,12 @@ -The insert_value_function is a function that is -responsible for traversing the tree and inserting new values into correct -place. -For example, the ngx_str_rbtree_insert_value functions is -designed to deal with ngx_str_t type. +To traverse a tree and insert new values, use the +"insert_value" functions. +For example, the ngx_str_rbtree_insert_value function deals +with the ngx_str_t type. +Its arguments are pointers to a root node of an insertion, the newly created +node to be added, and a tree sentinel. @@ -1092,10 +1135,6 @@ ngx_rbtree_node_t *sentinel) - -Its arguments are pointers to a root node of an insertion, newly created node -to be added, and a tree sentinel. - The traversal is pretty straightforward and can be demonstrated with the @@ -1143,9 +1182,10 @@ -The compare() is a classic comparator function returning -value less, equal or greater than zero. To speed up lookups and avoid comparing -user objects that can be big, integer hash field is used. +The compare() function is a classic comparator function that +returns a value less than, equal to, or greater than zero. +To speed up lookups and avoid comparing user objects that can be big, an integer +hash field is used. @@ -1168,7 +1208,7 @@ -to remove a node: +To remove a node, call the ngx_rbtree_delete() function: @@ -1182,21 +1222,20 @@ Hash table functions are declared in src/core/ngx_hash.h. -Exact and wildcard matching is supported. +Both exact and wildcard matching are supported. The latter requires extra setup and is described in a separate section below. -To initialize a hash, one needs to know the number of elements in advance, -so that nginx can build the hash optimally. +Before initializing a hash, you need to know the number of elements it will +hold so that nginx can build it optimally. Two parameters that need to be configured are max_size -and bucket_size. -The details of setting up these are provided in a separate +and bucket_size, as detailed in a separate document. -Usually, these two parameters are configurable by user. -Hash initialization settings are stored as the -ngx_hash_init_t type, -and the hash itself is ngx_hash_t: +They are usually configurable by the user. +Hash initialization settings are stored with the +ngx_hash_init_t type, and the hash itself is +ngx_hash_t: ngx_hash_t foo_hash; ngx_hash_init_t hash; @@ -1209,20 +1248,26 @@ hash.pool = cf->pool; hash.temp_pool = cf->temp_pool; -The key is a pointer to a function that creates hash integer -key from a string. -Two generic functions are provided: +The key is a pointer to a function that creates the hash +integer key from a string. +There are two generic key-creation functions: ngx_hash_key(data, len) and ngx_hash_key_lc(data, len). -The latter converts a string to lowercase and thus requires the passed string to -be writable. -If this is not true, NGX_HASH_READONLY_KEY flag -may be passed to the function, initializing array keys (see below). +The latter converts a string to all lowercase characters, so the passed string +must be writeable. +If that is not true, pass the NGX_HASH_READONLY_KEY flag +to the function, initializing the key array (see below). The hash keys are stored in ngx_hash_keys_arrays_t and are initialized with ngx_hash_keys_array_init(arr, type): +The second parameter (type) controls the amount of resources +preallocated for the hash and can be either NGX_HASH_SMALL or +NGX_HASH_LARGE. +The latter is appropriate if you expect the hash to contain thousands of +elements. + ngx_hash_keys_arrays_t foo_keys; @@ -1231,16 +1276,11 @@ ngx_hash_keys_array_init(&foo_keys, NGX_HASH_SMALL); -The second parameter can be either NGX_HASH_SMALL or -NGX_HASH_LARGE and controls the amount of preallocated -resources for the hash. -If you expect the hash to contain thousands elements, -use NGX_HASH_LARGE. - - - -The ngx_hash_add_key(keys_array, key, value, flags) -function is used to insert keys into hash keys array; + + + +To insert keys into a hash keys array, use the +ngx_hash_add_key(keys_array, key, value, flags) function: ngx_str_t k1 = ngx_string("key1"); ngx_str_t k2 = ngx_string("key2"); @@ -1251,17 +1291,21 @@ -Now, the hash table may be built using the call to -ngx_hash_init(hinit, key_names, nelts): +To build the hash table, call the +ngx_hash_init(hinit, key_names, nelts) function: ngx_hash_init(&hash, foo_keys.keys.elts, foo_keys.keys.nelts); -This may fail, if max_size or bucket_size -parameters are not big enough. -When the hash is built, ngx_hash_find(hash, key, name, len) -function may be used to look up elements: +The function fails if max_size or +bucket_size parameters are not big enough. + + + +When the hash is built, use the +ngx_hash_find(hash, key, name, len) function to look up +elements: my_data_t *data; ngx_uint_t key; @@ -1279,11 +1323,11 @@

-To create a hash that works with wildcards, -ngx_hash_combined_t type is used. +To create a hash that works with wildcards, use the +ngx_hash_combined_t type. It includes the hash type described above and has two additional keys arrays: dns_wc_head and dns_wc_tail. -The initialization of basic properties is done similarly to a usual hash: +The initialization of basic properties is similar to a regular hash: ngx_hash_init_t hash ngx_hash_combined_t foo_hash; @@ -1302,17 +1346,17 @@ ngx_hash_add_key(&foo_keys, &k1, &data1, NGX_HASH_WILDCARD_KEY); ngx_hash_add_key(&foo_keys, &k2, &data2, NGX_HASH_WILDCARD_KEY); -The function recognizes wildcards and adds keys into corresponding arrays. +The function recognizes wildcards and adds keys into the corresponding arrays. Please refer to the module -documentation for the description of the wildcard syntax and +documentation for the description of the wildcard syntax and the matching algorithm. Depending on the contents of added keys, you may need to initialize up to three -keys arrays: one for exact matching (described above), and two for matching -starting from head or tail of a string: +key arrays: one for exact matching (described above), and two more to enable +matching starting from the head or tail of a string: if (foo_keys.dns_wc_head.nelts) { @@ -1364,35 +1408,35 @@

-To allocate memory from system heap, the following functions are provided by -nginx: +To allocate memory from system heap, use the following functions: -ngx_alloc(size, log) — allocate memory from system heap. +ngx_alloc(size, log) — Allocate memory from system heap. This is a wrapper around malloc() with logging support. -Allocation error and debugging information is logged to log - - - -ngx_calloc(size, log) — same as -ngx_alloc(), but memory is filled with zeroes after -allocation - - - -ngx_memalign(alignment, size, log) — allocate aligned memory -from system heap. This is a wrapper around posix_memalign() -on those platforms which provide it. +Allocation error and debugging information is logged to log. + + + +ngx_calloc(size, log) — Allocate memory from system heap +like ngx_alloc(), but fill memory with zeros after +allocation. + + + +ngx_memalign(alignment, size, log) — Allocate aligned memory +from system heap. +This is a wrapper around posix_memalign() +on those platforms that provide that function. Otherwise implementation falls back to ngx_alloc() which -provides maximum alignment - - - -ngx_free(p) — free allocated memory. +provides maximum alignment. + + + +ngx_free(p) — Free allocated memory. This is a wrapper around free() @@ -1405,21 +1449,23 @@

-Most nginx allocations are done in pools. Memory allocated in an nginx pool is -freed automatically when the pool in destroyed. This provides good -allocation performance and makes memory control easy. - - - -A pool internally allocates objects in continuous blocks of memory. Once a -block is full, a new one is allocated and added to the pool memory -block list. When a large allocation is requested which does not fit into -a block, such allocation is forwarded to the system allocator and the +Most nginx allocations are done in pools. +Memory allocated in an nginx pool is freed automatically when the pool is +destroyed. +This provides good allocation performance and makes memory control easy. + + + +A pool internally allocates objects in continuous blocks of memory. +Once a block is full, a new one is allocated and added to the pool memory +block list. +When the requested allocation is too large to fit into a block, the request +is forwarded to the system allocator and the returned pointer is stored in the pool for further deallocation. -Nginx pool has the type ngx_pool_t. +The type for nginx pools is ngx_pool_t. The following operations are supported: @@ -1427,33 +1473,37 @@ -ngx_create_pool(size, log) — create a pool with given -block size. The pool object returned is allocated in the pool as well. - - - -ngx_destroy_pool(pool) — free all pool memory, including +ngx_create_pool(size, log) — Create a pool with specified +block size. +The pool object returned is allocated in the pool as well. + + + +ngx_destroy_pool(pool) — Free all pool memory, including the pool object itself. -ngx_palloc(pool, size) — allocate aligned memory from pool - - - -ngx_pcalloc(pool, size) — allocated aligned memory -from pool and fill it with zeroes - - - -ngx_pnalloc(pool, size) — allocate unaligned memory from pool. -Mostly used for allocating strings - - - -ngx_pfree(pool, p) — free memory, previously allocated -in the pool. -Only allocations, forwarded to the system allocator, can be freed. +ngx_palloc(pool, size) — Allocate aligned memory from the +specified pool. + + + +ngx_pcalloc(pool, size) — Allocate aligned memory +from the specified pool and fill it with zeroes. + + + +ngx_pnalloc(pool, size) — Allocate unaligned memory from the +specified pool. +Mostly used for allocating strings. + + + +ngx_pfree(pool, p) — Free memory that was previously +allocated in the specified pool. +Only allocations that result from requests forwarded to the system allocator +can be freed. @@ -1477,33 +1527,35 @@ -Since chain links ngx_chain_t are actively used in nginx, -nginx pool provides a way to reuse them. +Chain links (ngx_chain_t) are actively used in nginx, +so the nginx pool implementation provides a way to reuse them. The chain field of ngx_pool_t keeps a -list of previously allocated links ready for reuse. For efficient allocation of -a chain link in a pool, the function -ngx_alloc_chain_link(pool) should be used. -This function looks up a free chain link in the pool list and only if it's -empty allocates a new one. To free a link ngx_free_chain(pool, cl) -should be called. +list of previously allocated links ready for reuse. +For efficient allocation of a chain link in a pool, use the +ngx_alloc_chain_link(pool) function. +This function looks up a free chain link in the pool list and allocates a new +chain link if the pool list is empty. +To free a link, call the ngx_free_chain(pool, cl) function. Cleanup handlers can be registered in a pool. -Cleanup handler is a callback with an argument which is called when pool is +A cleanup handler is a callback with an argument which is called when pool is destroyed. -Pool is usually tied with a specific nginx object (like HTTP request) and -destroyed in the end of that object’s lifetime, releasing the object itself. -Registering a pool cleanup is a convenient way to release resources, close file -descriptors or make final adjustments to shared data, associated with the main -object. - - - -A pool cleanup is registered by calling ngx_pool_cleanup_add(pool, -size) which returns ngx_pool_cleanup_t pointer to -be filled by the caller. The size argument allows allocating -context for the cleanup handler. +A pool is usually tied to a specific nginx object (like an HTTP request) and is +destroyed when the object reaches the end of its lifetime. +Registering a pool cleanup is a convenient way to release resources, close +file descriptors or make final adjustments to the shared data associated with +the main object. + + + +To register a pool cleanup, call +ngx_pool_cleanup_add(pool, size), which returns a +ngx_pool_cleanup_t pointer to +be filled in by the caller. +Use the size argument to allocate context for the cleanup +handler. @@ -1534,16 +1586,18 @@ Shared memory is used by nginx to share common data between processes. -Function ngx_shared_memory_add(cf, name, size, tag) adds a -new shared memory entry ngx_shm_zone_t to the cycle. The -function receives name and size of the -zone. +The ngx_shared_memory_add(cf, name, size, tag) function adds +a new shared memory entry ngx_shm_zone_t to a cycle. +The function receives the name and size +of the zone. Each shared zone must have a unique name. -If a shared zone entry with the provided name exists, the old zone entry is -reused, if its tag value matches too. -Mismatched tag is considered an error. -Usually, the address of the module structure is passed as tag, making it -possible to reuse shared zones by name within one nginx module. +If a shared zone entry with the provided name and +tag already exists, the existing zone entry is reused. +The function fails with an error if an existing entry with the same name has a +different tag. +Usually, the address of the module structure is passed as +tag, making it possible to reuse shared zones by name within +one nginx module. @@ -1555,47 +1609,47 @@ -init — initialization callback, called after shared zone is -mapped to actual memory - - - -data — data context, used to pass arbitrary data to the +init — Initialization callback, called after the shared zone +is mapped to actual memory + + + +data — Data context, used to pass arbitrary data to the init callback -noreuse — flag, disabling shared zone reuse from the +noreuse — Flag that disables reuse of a shared zone from the old cycle -tag — shared zone tag - - - -shm — platform-specific object of type +tag — Shared zone tag + + + +shm — Platform-specific object of type ngx_shm_t, having at least the following fields: -addr — mapped shared memory address, initially NULL - - - -size — shared memory size - - - -name — shared memory name - - - -log — shared memory log - - - -exists — flag, showing that shared memory was inherited +addr — Mapped shared memory address, initially NULL + + + +size — Shared memory size + + + +name — Shared memory name + + + +log — Shared memory log + + + +exists — Flag that indicates shared memory was inherited from the master process (Windows-specific) @@ -1607,45 +1661,48 @@ Shared zone entries are mapped to actual memory in -ngx_init_cycle() after configuration is parsed. -On POSIX systems, mmap() syscall is used to create shared -anonymous mapping. -On Windows, CreateFileMapping()/MapViewOfFileEx() pair is -used. - - - -For allocating in shared memory, nginx provides slab pool -ngx_slab_pool_t. -In each nginx shared zone, a slab pool is automatically created for allocating -memory in that zone. +ngx_init_cycle() after the configuration is parsed. +On POSIX systems, the mmap() syscall is used to create the +shared anonymous mapping. +On Windows, the CreateFileMapping()/ +MapViewOfFileEx() pair is used. + + + +For allocating in shared memory, nginx provides the slab pool +ngx_slab_pool_t type. +A slab pool for allocating memory is automatically created in each nginx shared +zone. The pool is located in the beginning of the shared zone and can be accessed by the expression (ngx_slab_pool_t *) shm_zone->shm.addr. -Allocation in shared zone is done by calling one of the functions -ngx_slab_alloc(pool, size)/ngx_slab_calloc(pool, size). -Memory is freed by calling ngx_slab_free(pool, p). +To allocate memory in a shared zone, call either +ngx_slab_alloc(pool, size) or +ngx_slab_calloc(pool, size). +To free memory, call ngx_slab_free(pool, p). Slab pool divides all shared zone into pages. Each page is used for allocating objects of the same size. -Only the sizes which are powers of 2, and not less than 8, are considered. -Other sizes are rounded up to one of these values. -For each page, a bitmask is kept, showing which blocks within that page are in -use and which are free for allocation. -For sizes greater than half-page (usually, 2048 bytes), allocation is done by -entire pages. - - - -To protect data in shared memory from concurrent access, mutex is available in -the mutex field of ngx_slab_pool_t. -The mutex is used by the slab pool while allocating and freeing memory. -However, it can be used to protect any other user data structures, -allocated in the shared zone. -Locking is done by calling -ngx_shmtx_lock(&shpool->mutex), unlocking is done by -calling ngx_shmtx_unlock(&shpool->mutex). +The specified size must be a power of 2, and greater than the minimum size of +8 bytes. +Nonconforming values are rounded up. +A bitmask for each page tracks which blocks are in use and which are free for +allocation. +For sizes greater than a half page (which is usually 2048 bytes), allocation is +done an entire page at a time + + + +To protect data in shared memory from concurrent access, use the mutex +available in the mutex field of +ngx_slab_pool_t. +A mutex is most commonly used by the slab pool while allocating and freeing +memory, but it can be used to protect any other user data structures allocated +in the shared zone. +To lock or unlock a mutex, call +ngx_shmtx_lock(&shpool->mutex) or +ngx_shmtx_unlock(&shpool->mutex) respectively. @@ -1662,7 +1719,7 @@ /* error */ } -/* add an entry for 65k shared zone */ +/* add an entry for 64k shared zone */ shm_zone = ngx_shared_memory_add(cf, &name, 65536, &ngx_foo_module); if (shm_zone == NULL) { /* error */ @@ -1723,40 +1780,41 @@

-For logging nginx code uses ngx_log_t objects. -Nginx logger provides support for several types of output: +For logging nginx uses ngx_log_t objects. +The nginx logger supports several types of output: -stderr — logging to standard error output - - - -file — logging to file - - - -syslog — logging to syslog - - - -memory — logging to internal memory storage for development purposes. -The memory could be accessed later with debugger +stderr — Logging to standard error (stderr) + + + +file — Logging to a file + + + +syslog — Logging to syslog + + + +memory — Logging to internal memory storage for development purposes; the memory +can be accessed later with a debugger -A logger instance may actually be a chain of loggers, linked to each other with +A logger instance can be a chain of loggers, linked to each other with the next field. -Each message is written to all loggers in chain. - - - -Each logger has an error level which limits the messages written to that log. -The following error levels are supported by nginx: +In this case, each message is written to all loggers in the chain. + + + +For each logger, a severity level controls which messages are written to the +log (only events assigned that level or higher are logged). +The following severity levels are supported: @@ -1798,8 +1856,8 @@ -For debug logging, debug mask is checked as well. The following debug masks -exist: +For debug logging, the debug mask is checked as well. +The debug masks are: @@ -1850,13 +1908,13 @@ -ngx_log_error(level, log, err, fmt, ...) — error logging +ngx_log_error(level, log, err, fmt, ...) — Error logging ngx_log_debug0(level, log, err, fmt), -ngx_log_debug1(level, log, err, fmt, arg1) etc — debug -logging, up to 8 formatting arguments are supported +ngx_log_debug1(level, log, err, fmt, arg1) etc — Debug +logging with up to eight supported formatting arguments @@ -1865,8 +1923,8 @@ A log message is formatted in a buffer of size NGX_MAX_ERROR_STR (currently, 2048 bytes) on stack. -The message is prepended with error level, process PID, connection id (stored -in log->connection) and system error text. +The message is prepended with the severity level, process ID (PID), connection +ID (stored in log->connection), and the system error text. For non-debug messages log->handler is called as well to prepend more specific information to the log message. HTTP module sets ngx_http_log_error() function as log @@ -1874,11 +1932,6 @@ log->action), client request line, server name etc. - -Example: - - - /* specify what is currently done */ log->action = "sending mp4 to client”; @@ -1892,7 +1945,7 @@ -Logging result: +The example above results in log entries like these: @@ -1908,94 +1961,95 @@

-Cycle object keeps nginx runtime context, created from a specific -configuration. -The type of the cycle is ngx_cycle_t. -Upon configuration reload a new cycle is created from the new version of nginx +A cycle object stores the nginx runtime context created from a specific configuration. -The old cycle is usually deleted after a new one is successfully created. -Currently active cycle is held in the ngx_cycle global -variable and is inherited by newly started nginx workers. - - - -A cycle is created by the function ngx_init_cycle(). -The function receives the old cycle as the argument. -It's used to locate the configuration file and inherit as much resources as -possible from the old cycle to keep nginx running smoothly. -When nginx starts, a fake cycle called “init cycle” is created and is then -replaced by a normal cycle, built from configuration. - - - -Some members of the cycle: +Its type is ngx_cycle_t. +The current cycle is referenced by the ngx_cycle global +variable and inherited by nginx workers as they start. +Each time the nginx configuration is reloaded, a new cycle is created from the +new nginx configuration; the old cycle is usually deleted after the new one is +successfully created. + + + +A cycle is created by the ngx_init_cycle() function, which +takes the previous cycle as its argument. +The function locates the previous cycle's configuration file and inherits as +many resources as possible from the previous cycle. +A placeholder cycle called "init cycle" is created as nginx start, then is +replaced by an actual cycle built from configuration. + + + +Members of the cycle include: -pool — cycle pool. Created for each new cycle - - - -log — cycle log. Initially, this log is inherited from the -old cycle. -After reading configuration, this member is set to point to -new_log - - - -new_log — cycle log, created by the configuration. -It's affected by the root scope error_log directive +pool — Cycle pool. +Created for each new cycle. + + + +log — Cycle log. +Initially inherited from the old cycle, it is set to point to +new_log after the configuration is read. + + + +new_log — Cycle log, created by the configuration. +It's affected by the root-scope error_log directive. connections, connection_n — -array of connections of type ngx_connection_t, created by +Array of connections of type ngx_connection_t, created by the event module while initializing each nginx worker. -The number of connections connection_n is set by the -worker_connections directive +The worker_connections directive in the nginx configuration +sets the number of connections connection_n. free_connections, -free_connection_n — list and number of currently available +free_connection_n — List and number of currently available connections. -If no connections are available, nginx worker refuses to accept new clients or -connect to upstream servers - - - -files, files_n — array for mapping file +If no connections are available, an nginx worker refuses to accept new clients +or connect to upstream servers. + + + +files, files_n — Array for mapping file descriptors to nginx connections. This mapping is used by the event modules, having the -NGX_USE_FD_EVENT flag (currently, it's poll and devpoll) - - - -conf_ctx — array of core module configurations. -The configurations are created and filled while reading nginx configuration -files - - - -modules, modules_n — array of modules -ngx_module_t, both static and dynamic, loaded by current -configuration - - - -listening — array of listening objects +NGX_USE_FD_EVENT flag (currently, it's +poll and devpoll). + + + +conf_ctx — Array of core module configurations. +The configurations are created and filled during reading of nginx configuration +files. + + + +modules, modules_n — Array of modules +of type ngx_module_t, both static and dynamic, loaded by +the current configuration. + + + +listening — Array of listening objects of type ngx_listening_t. -Listening objects are normally added by the the listen +Listening objects are normally added by the listen directive of different modules which call the ngx_create_listening() function. -Based on listening objects, listen sockets are created by nginx - - - -paths — array of paths ngx_path_t. +Listen sockets are created based on the listening objects. + + + +paths — Array of paths of type ngx_path_t. Paths are added by calling the function ngx_add_path() from modules which are going to operate on certain directories. These directories are created by nginx after reading configuration, if missing. @@ -2004,41 +2058,43 @@ -path loader — executed only once in 60 seconds after starting or reloading -nginx. Normally, reads the directory and stores data in nginx shared -memory. The handler is called from a dedicated nginx process “nginx -cache loader” - - - -path manager — executed periodically. Normally, removes old files from the -directory and reflects these changes in nginx memory. The handler is -called from a dedicated nginx process “nginx cache manager” +path loader — Executes only once in 60 seconds after starting or reloading +nginx. +Normally, the loader reads the directory and stores data in nginx shared +memory. +The handler is called from the dedicated nginx process “nginx cache loader”. + + + +path manager — Executes periodically. +Normally, the manager removes old files from the directory and updates nginx +memory to reflect the changes. +The handler is called from the dedicated “nginx cache manager” process. -open_files — list of ngx_open_file_t -objects. -An open file object is created by calling the function +open_files — List of open file objects of type +ngx_open_file_t, which are created by calling the function ngx_conf_open_file(). -After reading configuration nginx opens all files from the -open_files list and stores file descriptors in the -fd field of each open file object. -The files are opened in append mode and created if missing. -The files from this list are reopened by nginx workers upon receiving the -reopen signal (usually it's USR1). -In this case the fd fields are changed to new descriptors. -The open files are currently used for logging - - - -shared_memory — list of shared memory zones, each added by +Currently, nginx uses this kind of open files for logging. +After reading the configuration, nginx opens all files in the +open_files list and stores each file descriptor in the +object's fd field. +The files are opened in append mode and are created if missing. +The files in the list are reopened by nginx workers upon receiving the +reopen signal (most often USR1). +In this case the descriptor in the fd field is changed to a +new value. + + + +shared_memory — List of shared memory zones, each added by calling the ngx_shared_memory_add() function. Shared zones are mapped to the same address range in all nginx processes and -are used to share common data, for example HTTP cache in-memory tree +are used to share common data, for example the HTTP cache in-memory tree. @@ -2053,109 +2109,111 @@ ngx_buf_t. Normally, it's used to hold data to be written to a destination or read from a source. -Buffer can reference data in memory and in file. -Technically it's possible that a buffer references both at the same time. +A buffer can reference data in memory or in a file and it's technically +possible for a buffer to reference both at the same time. Memory for the buffer is allocated separately and is not related to the buffer structure ngx_buf_t. -The structure ngx_buf_t has the following fields: +The ngx_buf_t structure has the following fields: -start, end — the boundaries of memory -block, allocated for the buffer - - - -pos, last — memory buffer boundaries, -normally a subrange of start .. end - - - -file_pos, file_last — file buffer -boundaries, these are offsets from the beginning of the file - - - -tag — unique value, used to distinguish buffers, created by -different nginx module, usually, for the purpose of buffer reuse - - - -file — file object - - - -temporary — flag, meaning that the buffer references -writable memory - - - -memory — flag, meaning that the buffer references read-only -memory - - - -in_file — flag, meaning that current buffer references data -in a file - - - -flush — flag, meaning that all data prior to this buffer -should be flushed - - - -recycled — flag, meaning that the buffer can be reused and -should be consumed as soon as possible - - - -sync — flag, meaning that the buffer carries no data or +start, end — The boundaries of the memory +block allocated for the buffer. + + + +pos, last — The boundaries of the memory +buffer; normally a subrange of start .. +end. + + + +file_pos, file_last — The boundaries of a +file buffer, expressed as offsets from the beginning of the file. + + + +tag — Unique value used to distinguish buffers; created by +different nginx modules, usually for the purpose of buffer reuse. + + + +file — File object. + + + +temporary — Flag indicating that the buffer references +writable memory. + + + +memory — Flag indicating that the buffer references read-only +memory. + + + +in_file — Flag indicating that the buffer references data +in a file. + + + +flush — Flag indicating that all data prior to the buffer +need to be flushed. + + + +recycled — Flag indicating that the buffer can be reused and +needs to be consumed as soon as possible. + + + +sync — Flag indicating that the buffer carries no data or special signal like flush or last_buf. -Normally, such buffers are considered an error by nginx. This flags allows -skipping the error checks - - - -last_buf — flag, meaning that current buffer is the last in -output - - - -last_in_chain — flag, meaning that there's no more data -buffers in a (sub)request - - - -shadow — reference to another buffer, related to the current -buffer. Usually current buffer uses data from the shadow buffer. Once current -buffer is consumed, the shadow buffer should normally also be marked as -consumed - - - -last_shadow — flag, meaning that current buffer is the last -buffer, referencing a particular shadow buffer - - - -temp_file — flag, meaning that the buffer is in a temporary -file +By default nginx considers such buffers an error condition, but this flag tells +nginx to skip the error check. + + + +last_buf — Flag indicating that the buffer is the last in +output. + + + +last_in_chain — Flag indicating that there are no more data +buffers in a request or subrequest. + + + +shadow — Reference to another ("shadow") buffer related to +the current buffer, usually in the sense that the buffer uses data from the +shadow. +When the buffer is consumed, the shadow buffer is normally also marked as +consumed. + + + +last_shadow — Flag indicating that the buffer is the last +one that references a particular shadow buffer. + + + +temp_file — Flag indicating that the buffer is in a temporary +file. -For input and output buffers are linked in chains. -Chain is a sequence of chain links ngx_chain_t, defined as -follows: +For input and output operations buffers are linked in chains. +A chain is a sequence of chain links of type ngx_chain_t, +defined as follows: @@ -2174,7 +2232,7 @@ -Example of using buffers and chains: +An example of using buffers and chains: @@ -2239,119 +2297,120 @@

-Connection type ngx_connection_t is a wrapper around a -socket descriptor. Some of the structure fields are: +The connection type ngx_connection_t is a wrapper around a +socket descriptor. +It includes the following fields: -fd — socket descriptor - - - -data — arbitrary connection context. -Normally, a pointer to a higher level object, built on top of the connection, -like HTTP request or Stream session - - - -read, write — read and write events for -the connection +fd — Socket descriptor + + + +data — Arbitrary connection context. +Normally, it is a pointer to a higher-level object built on top of the +connection, such as an HTTP request or a Stream session. + + + +read, write — Read and write events for +the connection. recv, send, recv_chain, send_chain — I/O operations -for the connection - - - -pool — connection pool - - - -log — connection log +for the connection. + + + +pool — Connection pool. + + + +log — Connection log. sockaddr, socklen, -addr_text — remote socket address in binary and text forms - - - -local_sockaddr, local_socklen — local +addr_text — Remote socket address in binary and text forms. + + + +local_sockaddr, local_socklen — Local socket address in binary form. Initially, these fields are empty. -Function ngx_connection_local_sockaddr() should be used to -get socket local address +Use the ngx_connection_local_sockaddr() function to get the +local socket address. proxy_protocol_addr, proxy_protocol_port -- PROXY protocol client address and port, if PROXY protocol is enabled for the -connection - - - -ssl — nginx connection SSL context - - - -reusable — flag, meaning, that the connection is at the -state, when it can be reused - - - -close — flag, meaning, that the connection is being reused -and should be closed +- PROXY protocol client address and port, if the PROXY protocol is enabled for +the connection. + + + +ssl — SSL context for the connection. + + + +reusable — Flag indicating the connection is in a state that +makes it eligible for reuse. + + + +close — Flag indicating that the connection is being reused +and needs to be closed. -An nginx connection can transparently encapsulate SSL layer. -In this case the connection ssl field holds a pointer to an +An nginx connection can transparently encapsulate the SSL layer. +In this case the connection's ssl field holds a pointer to an ngx_ssl_connection_t structure, keeping all SSL-related data for the connection, including SSL_CTX and SSL. -The handlers recv, send, -recv_chain, send_chain are set as well to -SSL functions. - - - -The number of connections per nginx worker is limited by the -worker_connections value. -All connection structures are pre-created when a worker starts and stored in +The recv, send, +recv_chain, and send_chain handlers are +set to SSL-enabled functions as well. + + + +The worker_connections directive in the nginx configuration +limits the number of connections per nginx worker. +All connection structures are precreated when a worker starts and stored in the connections field of the cycle object. -To reach out for a connection structure, ngx_get_connection(s, -log) function is used. -The function receives a socket descriptor s which needs to -be wrapped in a connection structure. - - - -Since the number of connections per worker is limited, nginx provides a -way to grab connections which are currently in use. -To enable or disable reuse of a connection, function -ngx_reusable_connection(c, reusable) is called. +To retrieve a connection structure, use the +ngx_get_connection(s, log) function. +It takes as its s argument a socket descriptor, which needs +to be wrapped in a connection structure. + + + +Because the number of connections per worker is limited, nginx provides a +way to grab connections that are currently in use. +To enable or disable reuse of a connection, call the +ngx_reusable_connection(c, reusable) function. Calling ngx_reusable_connection(c, 1) sets the -reuse flag of the connection structure and inserts the -connection in the reusable_connections_queue of the cycle. +reuse flag in the connection structure and inserts the +connection into the reusable_connections_queue of the cycle. Whenever ngx_get_connection() finds out there are no -available connections in the free_connections list of the -cycle, it calls ngx_drain_connections() to release a +available connections in the cycle's free_connections list, +it calls ngx_drain_connections() to release a specific number of reusable connections. For each such connection, the close flag is set and its read handler is called which is supposed to free the connection by calling ngx_close_connection(c) and make it available for reuse. To exit the state when a connection can be reused ngx_reusable_connection(c, 0) is called. -An example of reusable connections in nginx is HTTP client connections which -are marked as reusable until some data is received from the client. +HTTP client connections are an example of reusable connections in nginx; they +are marked as reusable until the first request byte is received from the client.

@@ -2366,92 +2425,93 @@

-Event object ngx_event_t in nginx provides a way to be -notified of a specific event happening. - - - -Some of the fields of the ngx_event_t are: +Event object ngx_event_t in nginx provides a mechanism +for notification that a specific event has occurred. + + + +Fields in ngx_event_t include: -data — arbitrary event context, used in event handler, -usually, a pointer to a connection, tied with the event - - - -handler — callback function to be invoked when the event -happens - - - -write — flag, meaning that this is the write event. -Used to distinguish between read and write events - - - -active — flag, meaning that the event is registered for -receiving I/O notifications, normally from notification mechanisms like epoll, -kqueue, poll - - - -ready — flag, meaning that the event has received an -I/O notification - - - -delayed — flag, meaning that I/O is delayed due to rate -limiting - - - -timer — Red-Black tree node for inserting the event into -the timer tree - - - -timer_set — flag, meaning that the event timer is set, -but not yet expired - - - -timedout — flag, meaning that the event timer has expired - - - -eof — read event flag, meaning that the eof has happened -while reading data - - - -pending_eof — flag, meaning that the eof is pending on the +data — Arbitrary event context used in event handlers, +usually as pointer to a connection related to the event. + + + +handler — Callback function to be invoked when the event +happens. + + + +write — Flag indicating a write event. +Absence of the flag indicates a read event. + + + +active — Flag indicating that the event is registered for +receiving I/O notifications, normally from notification mechanisms like +epoll, kqueue, poll. + + + +ready — Flag indicating that the event has received an +I/O notification. + + + +delayed — Flag indicating that I/O is delayed due to rate +limiting. + + + +timer — Red-black tree node for inserting the event into +the timer tree. + + + +timer_set — Flag indicating that the event timer is set and +not yet expired. + + + +timedout — Flag indicating that the event timer has expired. + + + +eof — Flag indicating that EOF occurred while reading data. + + + +pending_eof — Flag indicating that EOF is pending on the socket, even though there may be some data available before it. -The flag is delivered via EPOLLRDHUP epoll event or -EV_EOF kqueue flag - - - -error — flag, meaning that an error has happened while -reading (for read event) or writing (for write event) - - - -cancelable — timer event flag, meaning that the event -handler should be called while performing nginx worker graceful shutdown, event -though event timeout has not yet expired. The flag provides a way to finalize -certain activities, for example, flush log files - - - -posted — flag, meaning that the event is posted to queue - - - -queue — queue node for posting the event to a queue +The flag is delivered via the EPOLLRDHUP +epoll event or +EV_EOF kqueue flag. + + + +error — Flag indicating that an error occurred during +reading (for a read event) or writing (for a write event). + + + +cancelable — Timer event flag, used during graceful shutdown +of nginx workers, to signal that the event handler needs to be called even +though the event timeout has not yet expired. +The flag provides a way to finalize certain activities, for example flush log +files. + + + +posted — Flag indicating that the event is posted to a queue. + + + +queue — Queue node for posting the event to a queue. @@ -2463,24 +2523,23 @@

-Each connection, received with the -ngx_get_connection() call, has two events attached to it: -c->read and c->write. -These events are used to receive notifications about the socket being ready for -reading or writing. +Each connection obtained by calling the ngx_get_connection() +function has two attached events, c->read and +c->write, which are used for receiving notification that the +socket is ready for reading or writing. All such events operate in Edge-Triggered mode, meaning that they only trigger notifications when the state of the socket changes. -For example, doing a partial read on a socket will not make nginx deliver a -repeated read notification until more data arrive in the socket. +For example, doing a partial read on a socket does not make nginx deliver a +repeated read notification until more data arrives on the socket. Even when the underlying I/O notification mechanism is essentially -Level-Triggered (poll, select etc), nginx will turn the notifications into -Edge-Triggered. +Level-Triggered (poll, select etc), nginx +converts the notifications to Edge-Triggered. To make nginx event notifications consistent across all notifications systems -on different platforms, it's required, that the functions +on different platforms, the functions ngx_handle_read_event(rev, flags) and -ngx_handle_write_event(wev, lowat) are called after handling -an I/O socket notification or calling any I/O functions on that socket. -Normally, these functions are called once in the end of each read or write +ngx_handle_write_event(wev, lowat) must be called after +handling an I/O socket notification or calling any I/O functions on that socket. +Normally, the functions are called once at the end of each read or write event handler. @@ -2490,18 +2549,17 @@

-An event can be set to notify a timeout expiration. +An event can be set to send a notification when a timeout expires. The function ngx_add_timer(ev, timer) sets a timeout for an event, ngx_del_timer(ev) deletes a previously set timeout. -Timeouts currently set for all existing events, are kept in a global timeout -Red-Black tree ngx_event_timer_rbtree. -The key in that tree has the type ngx_msec_t and is the time -in milliseconds since the beginning of January 1, 1970 (modulus -ngx_msec_t max value) at which the event should expire. -The tree structure provides fast inserting and deleting operations, as well as -accessing the nearest timeouts. -The latter is used by nginx to find out for how long to wait for I/O events -and for expiring timeout events afterwards. +The global timeout red-black tree ngx_event_timer_rbtree +stores all timeouts currently set. +The key in the tree is of type ngx_msec_t and is the time +when the event expires, expressed in milliseconds since the midnight on of +January 1, 1970 modulus ngx_msec_t max value. +The tree structure enables fast insertion and deletion operations, as well as +access to the nearest timeouts, which nginx uses to find out how long to wait +for I/O events and for expiring timeout events.

@@ -2515,22 +2573,22 @@ Posting events is a good practice for simplifying code and escaping stack overflows. Posted events are held in a post queue. -The macro ngx_post_event(ev, q) posts the event +The ngx_post_event(ev, q) mscro posts the event ev to the post queue q. -Macro ngx_delete_posted_event(ev) deletes the event -ev from whatever queue it's currently posted. -Normally, events are posted to the ngx_posted_events queue. -This queue is processed late in the event loop — after all I/O and timer +The ngx_delete_posted_event(ev) macro deletes the event +ev from the queue it's currently posted in. +Normally, events are posted to the ngx_posted_events queue, +which is processed late in the event loop — after all I/O and timer events are already handled. The function ngx_event_process_posted() is called to process an event queue. -This function calls event handlers until the queue is not empty. This means -that a posted event handler can post more events to be processed within the -current event loop iteration. - - - -Example: +It calls event handlers until the queue is not empty. +This means that a posted event handler can post more events to be processed +within the current event loop iteration. + + + +An example: @@ -2583,48 +2641,51 @@

-All nginx processes which do I/O, have an event loop. -The only type of process which does not have I/O, is nginx master process which -spends most of its time in sigsuspend() call waiting for -signals to arrive. -Event loop is implemented in ngx_process_events_and_timers() -function. -This function is called repeatedly until the process exits. -It has the following stages: - - - +Except for the nginx master process, all nginx processes do I/O and so have an +event loop. +(The nginx master process instead spends most of its time in the + sigsuspend() call waiting for signals to arrive.) +The nginx event loop is implemented in the +ngx_process_events_and_timers() function, which is called +repeatedly until the process exits. + + + +The event loop has the following stages: + -find nearest timeout by calling ngx_event_find_timer(). -This function finds the leftmost timer tree node and returns the number of -milliseconds until that node expires - - - -process I/O events by calling a handler, specific to event notification +Find the timeout that is closest to expiring, by calling +ngx_event_find_timer(). +This function finds the leftmost node in the timer tree and returns the +number of milliseconds until the node expires. + + + +Process I/O events by calling a handler, specific to the event notification mechanism, chosen by nginx configuration. -This handler waits for at least one I/O event to happen, but no longer, than -the nearest timeout. -For each read or write event which has happened, the ready -flag is set and its handler is called. -For Linux, normally, the ngx_epoll_process_events() handler -is used which calls epoll_wait() to wait for I/O events - - - -expire timers by calling ngx_event_expire_timers(). -The timer tree is iterated from the leftmost element to the right until a not -yet expired timeout is found. +This handler waits for at least one I/O event to happen, but only until the next +timeout expires. +When a read or write event occurs, the ready +flag is set and the event's handler is called. +For Linux, the ngx_epoll_process_events() handler +is normally used, which calls epoll_wait() to wait for I/O +events. + + + +Expire timers by calling ngx_event_expire_timers(). +The timer tree is iterated from the leftmost element to the right until an +unexpired timeout is found. For each expired node the timedout event flag is set, -timer_set flag is reset, and the event handler is called - - - -process posted events by calling ngx_event_process_posted(). +the timer_set flag is reset, and the event handler is called + + + +Process posted events by calling ngx_event_process_posted(). The function repeatedly removes the first element from the posted events -queue and calls its handler until the queue gets empty +queue and calls the element's handler, until the queue is empty. @@ -4058,13 +4119,13 @@ Server configuration. -This configuraion applies to a single nginx server{}. +This configuration applies to a single nginx server{}. It stores server-specific settings for a module Location configuration. -This configuraion applies to a single location{}, if{} or limit_except() block. +This configuration applies to a single location{}, if{} or limit_except() block. This configuration stores settings specific to a location @@ -4299,7 +4360,7 @@ NGX_HTTP_REWRITE_PHASE — same as NGX_HTTP_SERVER_REWRITE_PHASE, but for a new location, -chosen at the prevous phase +chosen at the previous phase @@ -4611,24 +4672,24 @@ flags that control its behaviour: -NGX_HTTP_VAR_CHANGEABLE — allows redefining +NGX_HTTP_VAR_CHANGEABLE — allows redefining the variable; If another module will define a variable with such name, no conflict will happen. For example, this allows user to override variables using the directive. -NGX_HTTP_VAR_NOCACHEABLE — disables caching, +NGX_HTTP_VAR_NOCACHEABLE — disables caching, is useful for such variables as $time_local -NGX_HTTP_VAR_NOHASH — indicates that +NGX_HTTP_VAR_NOHASH — indicates that this variable is only accessible by index, not by name. This is a small optimization which may be used when it is known that the variable is not needed in modules like SSI or Perl. -NGX_HTTP_VAR_PREFIX — the name of this +NGX_HTTP_VAR_PREFIX — the name of this variable is a prefix. A handler must implement additional logic to obtain value of specific variable. @@ -4938,7 +4999,8 @@ The function ngx_http_named_location(r, name) redirects a request to a named location. The name of the location is passed as the -argument. The location is looked up among all named locations of the current +argument. +The location is looked up among all named locations of the current server, after which the requests switches to the NGX_HTTP_REWRITE_PHASE phase. @@ -4963,15 +5025,18 @@ Both functions ngx_http_internal_redirect(r, uri, args) and ngx_http_named_location(r, name) may be called when a request already has some contexts saved in its ctx field -by nginx modules. These contexts could become inconsistent with the new -location configuration. To prevent inconsistency, all request contexts are +by nginx modules. +These contexts could become inconsistent with the new +location configuration. +To prevent inconsistency, all request contexts are erased by both redirect functions. Redirected and rewritten requests become internal and may access the internal -locations. Internal requests have the internal flag set. +locations. +Internal requests have the internal flag set.