# HG changeset patch # User Vladimir Homutov # Date 1489668789 -10800 # Node ID be7490a66d1bd4244276183762ec329163d5cf9c # Parent a0a64fee6b13f990f996614172040aa9ee757446 Style: use long dash with non-breaking space where appropriate. diff -r a0a64fee6b13 -r be7490a66d1b xml/en/docs/dev/development_guide.xml --- a/xml/en/docs/dev/development_guide.xml Thu Mar 16 15:02:34 2017 +0300 +++ b/xml/en/docs/dev/development_guide.xml Thu Mar 16 15:53:09 2017 +0300 @@ -19,7 +19,7 @@ -auto - build scripts +auto — build scripts @@ -28,17 +28,17 @@ -core - basic types and functions - string, array, log, +core — basic types and functions — string, array, log, pool etc -event - event core +event — event core -modules - event notification modules: epoll, kqueue, +modules — event notification modules: epoll, kqueue, select etc @@ -47,16 +47,16 @@ -http - core HTTP module and common code +http — core HTTP module and common code -modules - other HTTP modules - - - -v2 - HTTPv2 +modules — other HTTP modules + + + +v2 — HTTPv2 @@ -64,11 +64,11 @@ -mail - mail modules - - - -os - platform-specific code +mail — mail modules + + + +os — platform-specific code @@ -85,7 +85,7 @@ -stream - stream modules +stream — stream modules @@ -161,34 +161,34 @@ -NGX_OK - operation succeeded - - - -NGX_ERROR - operation failed - - - -NGX_AGAIN - operation incomplete, function should be called +NGX_OK — operation succeeded + + + +NGX_ERROR — operation failed + + + +NGX_AGAIN — operation incomplete, function should be called again -NGX_DECLINED - operation rejected, for example, if disabled +NGX_DECLINED — operation rejected, for example, if disabled in configuration. This is never an error -NGX_BUSY - resource is not available - - - -NGX_DONE - operation done or continued elsewhere. +NGX_BUSY — resource is not available + + + +NGX_DONE — operation done or continued elsewhere. Also used as an alternative success code -NGX_ABORT - function was aborted. +NGX_ABORT — function was aborted. Also used as an alternative error code @@ -443,14 +443,14 @@ -%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 * +%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 * @@ -467,7 +467,7 @@ /* set n here */ -len = ngx_sprintf(buf, "%ui", n) - buf; +len = ngx_sprintf(buf, "%ui", n) — buf; @@ -485,28 +485,28 @@ -ngx_atoi(line, n) - converts a string of given length to a +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 +ngx_atosz(line, n) — same for ssize_t type -ngx_atoof(line, n) - same for off_t +ngx_atoof(line, n) — same for off_t type -ngx_atotm(line, n) - same for time_t +ngx_atotm(line, n) — same for time_t type -ngx_atofp(line, n, point) - converts a fixed point floating +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 @@ -517,7 +517,7 @@ -ngx_hextoi(line, n) - converts hexadecimal representation of +ngx_hextoi(line, n) — converts hexadecimal representation of a positive integer to ngx_int_t. Returns NGX_ERROR on error @@ -613,7 +613,7 @@ /* all captures */ for (i = 0; i < n * 2; i += 2) { value.data = input.data + captures[i]; - value.len = captures[i + 1] - captures[i]; + value.len = captures[i + 1] — captures[i]; } /* accessing named captures */ @@ -631,7 +631,7 @@ /* captured value */ value.data = &input.data[captures[n]]; - value.len = captures[n + 1] - captures[n]; + value.len = captures[n + 1] — captures[n]; } @@ -862,25 +862,25 @@ 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, +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_add(h, n) — add second queue to the first queue ngx_queue_head(h), -ngx_queue_last(h) - get first or last queue node +ngx_queue_last(h) — get first or last queue node @@ -889,7 +889,7 @@ -ngx_queue_data(q, type, link) - get reference to the beginning of a +ngx_queue_data(q, type, link) — get reference to the beginning of a queue node data structure, considering the queue field offset in it @@ -1241,8 +1241,8 @@ The lookup in a combined hash is handled by the ngx_hash_find_combined(chash, key, name, len): -/* key = "bar.example.org"; - will match ".example.org" */ -/* key = "foo.example.com"; - will match "foo.*" */ +/* key = "bar.example.org"; — will match ".example.org" */ +/* key = "foo.example.com"; — will match "foo.*" */ hkey = ngx_hash_key(key.data, key.len); res = ngx_hash_find_combined(&foo_hash, hkey, key.data, key.len); @@ -1270,19 +1270,19 @@ -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_calloc(size, log) — same as ngx_alloc(), but memory is filled with zeroes after allocation -ngx_memalign(alignment, size, log) - allocate aligned memory +ngx_memalign(alignment, size, log) — allocate aligned memory from system heap. This is a wrapper around posix_memalign() on those platforms which provide it. Otherwise implementation falls back to ngx_alloc() which @@ -1290,7 +1290,7 @@ -ngx_free(p) - free allocated memory. +ngx_free(p) — free allocated memory. This is a wrapper around free() @@ -1325,31 +1325,31 @@ -ngx_create_pool(size, log) - create a pool with given +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_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 +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. +ngx_pnalloc(pool, size) — allocate unaligned memory from pool. Mostly used for allocating strings -ngx_pfree(pool, p) - free memory, previously allocated +ngx_pfree(pool, p) — free memory, previously allocated in the pool. Only allocations, forwarded to the system allocator, can be freed. @@ -1453,47 +1453,47 @@ -init - initialization callback, called after shared zone is +init — initialization callback, called after shared zone is mapped to actual memory -data - data context, used to pass arbitrary data to the +data — data context, used to pass arbitrary data to the init callback -noreuse - flag, disabling shared zone reuse from the +noreuse — flag, disabling shared zone reuse 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, showing that shared memory was inherited from the master process (Windows-specific) @@ -1627,19 +1627,19 @@ -stderr - logging to standard error output - - - -file - logging to file - - - -syslog - logging to syslog - - - -memory - logging to internal memory storage for development purposes. +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 @@ -1748,12 +1748,12 @@ -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 +ngx_log_debug1(level, log, err, fmt, arg1) etc — debug logging, up to 8 formatting arguments are supported @@ -1833,23 +1833,23 @@ -pool - cycle pool. Created for each new cycle - - - -log - cycle log. Initially, this log is inherited from the +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. +new_log — cycle log, created by the configuration. It's affected by the root scope error_log directive -connections, connections_n - per-worker +connections, connections_n — per-worker array of connections of type ngx_connection_t, created by the event module while initializing each nginx worker. The number of connections is set by the worker_connections @@ -1858,32 +1858,32 @@ free_connections, -free_connections_n - the and number of currently available +free_connections_n — the and number of currently available connections. If no connections are available, nginx worker refuses to accept new clients -files, files_n - array for mapping file +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. +conf_ctx — array of core module configurations. The configurations are created and filled while reading nginx configuration files -modules, modules_n - array of modules +modules, modules_n — array of modules ngx_module_t, both static and dynamic, loaded by current configuration -listening - array of listening objects +listening — array of listening objects ngx_listening_t. Listening objects are normally added by the the listen directive of different modules which call the @@ -1892,7 +1892,7 @@ -paths - array of paths ngx_path_t. +paths — array of paths 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. @@ -1901,14 +1901,14 @@ -path loader - executed only once in 60 seconds after starting or reloading +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 +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" @@ -1917,7 +1917,7 @@ -open_files - list of ngx_open_file_t +open_files — list of ngx_open_file_t objects. An open file object is created by calling the function ngx_conf_open_file(). @@ -1932,7 +1932,7 @@ -shared_memory - list of shared memory zones, each added by +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 @@ -1964,85 +1964,85 @@ -start, end - the boundaries of memory +start, end — the boundaries of memory block, allocated for the buffer -pos, last - memory buffer boundaries, +pos, last — memory buffer boundaries, normally a subrange of start .. end -file_pos, file_last - file buffer +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 +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 +file — file object + + + +temporary — flag, meaning that the buffer references writable memory -memory - flag, meaning that the buffer references read-only +memory — flag, meaning that the buffer references read-only memory -in_file - flag, meaning that current buffer references data +in_file — flag, meaning that current buffer references data in a file -flush - flag, meaning that all data prior to this buffer +flush — flag, meaning that all data prior to this buffer should be flushed -recycled - flag, meaning that the buffer can be reused and +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 +sync — flag, meaning 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 +last_buf — flag, meaning that current buffer is the last in output -last_in_chain - flag, meaning that there's no more data +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 +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 +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 +temp_file — flag, meaning that the buffer is in a temporary file @@ -2144,41 +2144,41 @@ -fd - socket descriptor - - - -data - arbitrary connection context. +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 +read, write — read and write events for the connection recv, send, -recv_chain, send_chain - I/O operations +recv_chain, send_chain — I/O operations for the connection -pool - connection pool - - - -log - connection log +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 @@ -2192,16 +2192,16 @@ -ssl - nginx connection SSL context - - - -reusable - flag, meaning, that the connection is at the +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 +close — flag, meaning, that the connection is being reused and should be closed @@ -2275,80 +2275,80 @@ -data - arbitrary event context, used in event handler, +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 +handler — callback function to be invoked when the event happens -write - flag, meaning that this is the write event. +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 +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 +ready — flag, meaning that the event has received an I/O notification -delayed - flag, meaning that I/O is delayed due to rate +delayed — flag, meaning that I/O is delayed due to rate limiting -timer - Red-Black tree node for inserting the event into +timer — Red-Black tree node for inserting the event into the timer tree -timer_set - flag, meaning that the event timer is set, +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 +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 +pending_eof — flag, meaning that the 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 +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 +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 +posted — flag, meaning that the event is posted to queue + + + +queue — queue node for posting the event to a queue @@ -2417,7 +2417,7 @@ 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 +This queue 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. @@ -2552,7 +2552,7 @@ -NGX_PROCESS_MASTER - the master process runs the +NGX_PROCESS_MASTER — the master process runs the ngx_master_process_cycle() function. Master process does not have any I/O and responds only to signals. It reads configuration, creates cycles, starts and controls child processes @@ -2564,7 +2564,7 @@ -NGX_PROCESS_WORKER - the worker process runs the +NGX_PROCESS_WORKER — the worker process runs the ngx_worker_process_cycle() function. Worker processes are started by master and handle client connections. They also respond to signals and channel commands, sent from master @@ -2576,7 +2576,7 @@ -NGX_PROCESS_SINGLE - single process is the only type +NGX_PROCESS_SINGLE — single process is the only type of processes which exist in the master_process off mode. The cycle function for this process is ngx_single_process_cycle(). @@ -2589,7 +2589,7 @@ -NGX_PROCESS_HELPER - currently, there are two types of +NGX_PROCESS_HELPER — currently, there are two types of helper processes: cache manager and cache loader. Both of them share the same cycle function ngx_cache_manager_process_cycle(). @@ -2609,7 +2609,7 @@ -NGX_SHUTDOWN_SIGNAL (SIGQUIT) - graceful +NGX_SHUTDOWN_SIGNAL (SIGQUIT) — graceful shutdown. Upon receiving this signal master process sends shutdown signal to all child processes. @@ -2676,7 +2676,7 @@ -NGX_REOPEN_SIGNAL (SIGUSR1) - reopen +NGX_REOPEN_SIGNAL (SIGUSR1) — reopen files. Master process passes this signal to workers. Worker processes reopen all open_files from the cycle @@ -2688,7 +2688,7 @@ -NGX_CHANGEBIN_SIGNAL (SIGUSR2) - change +NGX_CHANGEBIN_SIGNAL (SIGUSR2) — change nginx binary. Master process starts a new nginx binary and passes there a list of all listen sockets. @@ -2751,7 +2751,7 @@ -ngx_module_type - the type of module to build. +ngx_module_type — the type of module to build. Possible options are CORE, HTTP, HTTP_FILTER, HTTP_INIT_FILTER, HTTP_AUX_FILTER, MAIL, @@ -2759,7 +2759,7 @@ -ngx_module_name - the name of the module. +ngx_module_name — the name of the module. A whitespace separated values list is accepted and may be used to build multiple modules from a single set of source files. The first name indicates the name of the output binary for a dynamic module. @@ -2767,27 +2767,27 @@ -ngx_addon_name - supplies the name of the module in the +ngx_addon_name — supplies the name of the module in the console output text of the configure script. -ngx_module_srcs - a whitespace separated list of source +ngx_module_srcs — a whitespace separated list of source files used to compile the module. The $ngx_addon_dir variable can be used as a placeholder for the path of the module source. -ngx_module_incs - include paths required to build the module - - - -ngx_module_deps - a list of module's header files. - - - -ngx_module_libs - a list of libraries to link with the +ngx_module_incs — include paths required to build the module + + + +ngx_module_deps — a list of module's header files. + + + +ngx_module_libs — a list of libraries to link with the module. For example, libpthread would be linked using ngx_module_libs=-lpthread. @@ -2799,14 +2799,14 @@ -ngx_module_link - set by the build system to +ngx_module_link — set by the build system to DYNAMIC for a dynamic module or ADDON for a static module and used to perform different actions depending on linking type. -ngx_module_order - sets the load order for the module which +ngx_module_order — sets the load order for the module which is useful for HTTP_FILTER and HTTP_AUX_FILTER module types. The order is stored in a reverse list. @@ -3106,19 +3106,19 @@ -NGX_CONF_NOARGS - directive without arguments - - -NGX_CONF_1MORE - one required argument - -NGX_CONF_2MORE - two required arguments - - -NGX_CONF_TAKE1..7 - exactly 1..7 arguments - - - -NGX_CONF_TAKE12, 13, 23, 123, 1234 - one or two arguments, +NGX_CONF_NOARGS — directive without arguments + + +NGX_CONF_1MORE — one required argument + +NGX_CONF_2MORE — two required arguments + + +NGX_CONF_TAKE1..7 — exactly 1..7 arguments + + + +NGX_CONF_TAKE12, 13, 23, 123, 1234 — one or two arguments, or other combinations @@ -3129,13 +3129,13 @@ -NGX_CONF_BLOCK - the directive is a block, i.e. it may +NGX_CONF_BLOCK — the directive is a block, i.e. it may contain other directives in curly braces, or even implement its own parser to handle contents inside. -NGX_CONF_FLAG - the directive value is a flag, a boolean +NGX_CONF_FLAG — the directive value is a flag, a boolean value represented by “on” or “off” strings. @@ -3146,63 +3146,63 @@ -NGX_MAIN_CONF - top level configuration - - - -NGX_HTTP_MAIN_CONF - in the http block - - - -NGX_HTTP_SRV_CONF - in the http server block - - - -NGX_HTTP_LOC_CONF - in the http location - - - -NGX_HTTP_UPS_CONF - in the http upstream block - - - -NGX_HTTP_SIF_CONF - in the http server “if” - - - -NGX_HTTP_LIF_CONF - in the http location “if” - - - -NGX_HTTP_LMT_CONF - in the http “limit_except” - - - -NGX_STREAM_MAIN_CONF - in the stream block - - - -NGX_STREAM_SRV_CONF - in the stream server block - - - -NGX_STREAM_UPS_CONF - in the stream upstream block - - - -NGX_MAIL_MAIN_CONF - in the the mail block - - - -NGX_MAIL_SRV_CONF - in the mail server block - - - -NGX_EVENT_CONF - in the event block - - - -NGX_DIRECT_CONF - used by modules that don't +NGX_MAIN_CONF — top level configuration + + + +NGX_HTTP_MAIN_CONF — in the http block + + + +NGX_HTTP_SRV_CONF — in the http server block + + + +NGX_HTTP_LOC_CONF — in the http location + + + +NGX_HTTP_UPS_CONF — in the http upstream block + + + +NGX_HTTP_SIF_CONF — in the http server “if” + + + +NGX_HTTP_LIF_CONF — in the http location “if” + + + +NGX_HTTP_LMT_CONF — in the http “limit_except” + + + +NGX_STREAM_MAIN_CONF — in the stream block + + + +NGX_STREAM_SRV_CONF — in the stream server block + + + +NGX_STREAM_UPS_CONF — in the stream upstream block + + + +NGX_MAIL_MAIN_CONF — in the the mail block + + + +NGX_MAIL_SRV_CONF — in the mail server block + + + +NGX_EVENT_CONF — in the event block + + + +NGX_DIRECT_CONF — used by modules that don't create a hierarchy of contexts and store module configuration directly in ctx @@ -3220,66 +3220,66 @@ -ngx_conf_set_flag_slot - converts literal +ngx_conf_set_flag_slot — converts literal “on” or “off” strings into ngx_flag_t type with values 1 or 0 -ngx_conf_set_str_slot - stores string as a value of the +ngx_conf_set_str_slot — stores string as a value of the ngx_str_t type -ngx_conf_set_str_array_slot - appends +ngx_conf_set_str_array_slot — appends ngx_array_t of ngx_str_t with a new value. The array is created if not yet exists -ngx_conf_set_keyval_slot - appends +ngx_conf_set_keyval_slot — appends ngx_array_t of ngx_keyval_t with a new value, where key is the first string and value is second. The array is created if not yet exists -ngx_conf_set_num_slot - converts directive argument +ngx_conf_set_num_slot — converts directive argument to a ngx_int_t value -ngx_conf_set_size_slot - converts +ngx_conf_set_size_slot — converts size to size_t value in bytes -ngx_conf_set_off_slot - converts +ngx_conf_set_off_slot — converts offset to off_t value in bytes -ngx_conf_set_msec_slot - converts +ngx_conf_set_msec_slot — converts time to ngx_msec_t value in milliseconds -ngx_conf_set_sec_slot - converts +ngx_conf_set_sec_slot — converts time to time_t value in seconds -ngx_conf_set_bufs_slot - converts two arguments +ngx_conf_set_bufs_slot — converts two arguments into ngx_bufs_t that holds ngx_int_t number and size of buffers -ngx_conf_set_enum_slot - converts argument +ngx_conf_set_enum_slot — converts argument into ngx_uint_t value. The null-terminated array of ngx_conf_enum_t passed in the post field defines acceptable strings and corresponding @@ -3287,7 +3287,7 @@ -ngx_conf_set_bitmask_slot - arguments are converted to +ngx_conf_set_bitmask_slot — arguments are converted to ngx_uint_t value and OR'ed with the resulting value, forming a bitmask. The null-terminated array of ngx_conf_bitmask_t passed in @@ -3296,7 +3296,7 @@ -set_path_slot - converts arguments to +set_path_slot — converts arguments to ngx_path_t type and performs all required initializations. See the proxy_temp_path @@ -3304,7 +3304,7 @@ -set_access_slot - converts arguments to file permissions +set_access_slot — converts arguments to file permissions mask. See the proxy_store_access @@ -3330,31 +3330,31 @@ -NGX_HTTP_MAIN_CONF_OFFSET - http block configuration - - - -NGX_HTTP_SRV_CONF_OFFSET - http server configuration - - - -NGX_HTTP_LOC_CONF_OFFSET - http location configuration - - - -NGX_STREAM_MAIN_CONF_OFFSET - stream block configuration - - - -NGX_STREAM_SRV_CONF_OFFSET - stream server configuration - - - -NGX_MAIL_MAIN_CONF_OFFSET - mail block configuration - - - -NGX_MAIL_SRV_CONF_OFFSET - mail server configuration +NGX_HTTP_MAIN_CONF_OFFSET — http block configuration + + + +NGX_HTTP_SRV_CONF_OFFSET — http server configuration + + + +NGX_HTTP_LOC_CONF_OFFSET — http location configuration + + + +NGX_STREAM_MAIN_CONF_OFFSET — stream block configuration + + + +NGX_STREAM_SRV_CONF_OFFSET — stream server configuration + + + +NGX_MAIL_MAIN_CONF_OFFSET — mail block configuration + + + +NGX_MAIL_SRV_CONF_OFFSET — mail server configuration @@ -3491,7 +3491,7 @@ -connection - pointer to a ngx_connection_t +connection — pointer to a ngx_connection_t client connection object. Several requests may reference the same connection object at the same time - one main request and its subrequests. @@ -3514,7 +3514,7 @@ -ctx - array of HTTP module contexts. +ctx — array of HTTP module contexts. Each module of type NGX_HTTP_MODULE can store any value (normally, a pointer to a structure) in the request. The value is stored in the ctx array at the module's @@ -3525,12 +3525,12 @@ -ngx_http_get_module_ctx(r, module) - returns +ngx_http_get_module_ctx(r, module) — returns module's context -ngx_http_set_ctx(r, c, module) - sets c +ngx_http_set_ctx(r, c, module) — sets c as module's context @@ -3539,7 +3539,7 @@ -main_conf, srv_conf, loc_conf - arrays of current request +main_conf, srv_conf, loc_conf — arrays of current request configurations. Configurations are stored at module's ctx_index positions @@ -3554,15 +3554,15 @@ -cache - request cache object for caching upstream response - - - -upstream - request upstream object for proxying - - - -pool - request pool. +cache — request cache object for caching upstream response + + + +upstream — request upstream object for proxying + + + +pool — request pool. This pool is destroyed when the request is deleted. The request object itself is allocated in this pool. For allocations which should be available throughout the client connection's @@ -3570,11 +3570,11 @@ -header_in - buffer where client HTTP request header in read - - - -headers_in, headers_out - input and output HTTP headers +header_in — buffer where client HTTP request header in read + + + +headers_in, headers_out — input and output HTTP headers objects. Both objects contain the headers field of type ngx_list_t keeping the raw list of headers. @@ -3584,17 +3584,17 @@ -request_body - client request body object - - - -start_sec, start_msec - time point when the request was +request_body — client request body object + + + +start_sec, start_msec — time point when the request was created. Used for tracking request duration -method, method_name - numeric and textual representation of +method, method_name — numeric and textual representation of client HTTP request method. Numeric values for methods are defined in src/http/ngx_http_request.h with macros @@ -3610,12 +3610,12 @@ -request_line, unparsed_uri - client original request line +request_line, unparsed_uri — client original request line and URI -uri, args, exten - current request URI, arguments and file +uri, args, exten — current request URI, arguments and file extention. The URI value here might differ from the original URI sent by the client due to normalization. @@ -3624,24 +3624,24 @@ -main - pointer to a main request object. +main — pointer to a main request object. This object is created to process client HTTP request, as opposed to subrequests, created to perform a specific sub-task within the main request -parent - pointer to a parent request of a subrequest - - - -postponed - list of output buffers and subrequests in the +parent — pointer to a parent request of a subrequest + + + +postponed — list of output buffers and subrequests in the order they are sent and created. The list is used by the postpone filter to provide consistent request output, when parts of it are created by subrequests -post_subrequest - pointer to a handler with context to be +post_subrequest — pointer to a handler with context to be called when a subrequest gets finalized. Unused for main requests @@ -3649,7 +3649,7 @@ -posted_requests - list of requests to be started or +posted_requests — list of requests to be started or resumed. Starting or resuming is done by calling the request's write_event_handler. @@ -3671,11 +3671,11 @@ -phase_handler - index of current request phase - - - -ncaptures, captures, captures_data - regex captures produced +phase_handler — index of current request phase + + + +ncaptures, captures, captures_data — regex captures produced by the last regex match of the request. While processing a request, there's a number of places where a regex match can happen: map lookup, server lookup by SNI or HTTP Host, rewrite, proxy_redirect @@ -3689,7 +3689,7 @@ -count - request reference counter. +count — request reference counter. The field only makes sense for the main request. Increasing the counter is done by simple r->main->count++. To decrease the counter ngx_http_finalize_request(r, rc) @@ -3699,7 +3699,7 @@ -subrequests - current subrequest nesting level. +subrequests — current subrequest nesting level. Each subrequest gets the nesting level of its parent decreased by one. Once the value reaches zero an error is generated. The value for the main request is defined by the @@ -3707,7 +3707,7 @@ -uri_changes - number of URI changes left for the request. +uri_changes — number of URI changes left for the request. The total number of times a request can change its URI is limited by the NGX_HTTP_MAX_URI_CHANGES constant. With each change the value is decreased until it reaches zero. @@ -3717,14 +3717,14 @@ -blocked - counter of blocks held on the request. +blocked — counter of blocks held on the request. While this value is non-zero, request cannot be terminated. Currently, this value is increased by pending AIO operations (POSIX AIO and thread operations) and active cache lock -buffered - bitmask showing which modules have buffered the +buffered — bitmask showing which modules have buffered the output produced by the request. A number of filters can buffer output, for example sub_filter can buffer data due to a partial string match, copy filter can buffer data because of the lack @@ -3733,13 +3733,13 @@ -header_only - flag showing that output does not require body. +header_only — flag showing that output does not require body. For example, this flag is used by HTTP HEAD requests -keepalive - flag showing if client connection keepalive is +keepalive — flag showing if client connection keepalive is supported. The value is inferred from HTTP version and

Connection

header value @@ -3747,36 +3747,36 @@ -header_sent - flag showing that output header has already +header_sent — flag showing that output header has already been sent by the request -internal - flag showing that current request is internal. +internal — flag showing that current request is internal. To enter the internal state, a request should pass through an internal redirect or be a subrequest. Internal requests are allowed to enter internal locations -allow_ranges - flag showing that partial response can be +allow_ranges — flag showing that partial response can be sent to client, if requested by the HTTP Range header -subrequest_ranges - flag showing that a partial response is +subrequest_ranges — flag showing that a partial response is allowed to be sent while processing a subrequest -single_range - flag showing that only a single continuous +single_range — flag showing that only a single continuous range of output data can be sent to the client. This flag is usually set when sending a stream of data, for example from a proxied server, and the entire response is not available at once -main_filter_need_in_memory, filter_need_in_memory - flags +main_filter_need_in_memory, filter_need_in_memory — flags showing that the output should be produced in memory buffers but not in files. This is a signal to the copy filter to read data from file buffers even if sendfile is enabled. @@ -3791,7 +3791,7 @@ -filter_need_temporary - flag showing that the request output +filter_need_temporary — flag showing that the request output should be produced in temporary buffers, but not in readonly memory buffers or file buffers. This is used by filters which may change output directly in the buffers, where @@ -4047,7 +4047,7 @@ -NGX_HTTP_FIND_CONFIG_PHASE - a special phase used to choose a +NGX_HTTP_FIND_CONFIG_PHASE — a special phase used to choose a location based on request URI. This phase does not allow installing any handlers. It only performs the default action of choosing a location. @@ -4058,13 +4058,13 @@ -NGX_HTTP_REWRITE_PHASE - same as +NGX_HTTP_REWRITE_PHASE — same as NGX_HTTP_SERVER_REWRITE_PHASE, but for a new location, chosen at the prevous phase -NGX_HTTP_POST_REWRITE_PHASE - a special phase, used to +NGX_HTTP_POST_REWRITE_PHASE — a special phase, used to redirect the request to a new location, if the URI was changed during rewrite. The redirect is done by going back to NGX_HTTP_FIND_CONFIG_PHASE. @@ -4072,7 +4072,7 @@ -NGX_HTTP_PREACCESS_PHASE - a common phase for different +NGX_HTTP_PREACCESS_PHASE — a common phase for different types of handlers, not associated with access check. Standard nginx modules ngx_http_limit_conn_module @@ -4082,7 +4082,7 @@ -NGX_HTTP_ACCESS_PHASE - used to check access permissions +NGX_HTTP_ACCESS_PHASE — used to check access permissions for the request. Standard nginx modules such as ngx_http_access_module and @@ -4095,7 +4095,7 @@ -NGX_HTTP_POST_ACCESS_PHASE - a special phase for the +NGX_HTTP_POST_ACCESS_PHASE — a special phase for the satisfy any case. If some access phase handlers denied the access and none of them allowed, the @@ -4104,13 +4104,13 @@ -NGX_HTTP_TRY_FILES_PHASE - a special phase, for the +NGX_HTTP_TRY_FILES_PHASE — a special phase, for the feature. No handlers are allowed at this phase -NGX_HTTP_CONTENT_PHASE - a phase, at which the response +NGX_HTTP_CONTENT_PHASE — a phase, at which the response is supposed to be generated. Multiple nginx standard modules register their handers at this phase, for example @@ -4203,17 +4203,17 @@ -NGX_OK - proceed to the next phase - - - -NGX_DECLINED - proceed to the next handler of the current +NGX_OK — proceed to the next phase + + + +NGX_DECLINED — proceed to the next handler of the current phase. If current handler is the last in current phase, move to the next phase -NGX_AGAIN, NGX_DONE - suspend phase handling until some +NGX_AGAIN, NGX_DONE — suspend phase handling until some future event. This can be for example asynchronous I/O operation or just a delay. It is supposed, that phase handling will be resumed later by calling