nginx-site: xml/en/docs/dev/development

comparison xml/en/docs/dev/development_guide.xml @ 2007:c559be34257b

DevGuide: language and style fixes, second part.

author	Roman Arutyunyan <arut@nginx.com>
date	Wed, 05 Jul 2017 14:58:38 +0300
parents	1b086de6a05b
children	1f2f9fa97065

comparison

equal deleted inserted replaced

-:b13d6412b335
+:c559be34257b
 <section name="Processes" id="processes">
 <para>
 There are several types of processes in nginx.
-The type of current process is kept in the <literal>ngx_process</literal>
+The type of a process is kept in the <literal>ngx_process</literal>
-global variable:
+global variable, and is one of the following:
 </para>
 <list type="bullet">
 <listitem>
 <para>
-<literal>NGX_PROCESS_MASTER</literal> — the master process runs the
+<literal>NGX_PROCESS_MASTER</literal> — The master process, which reads the
-<literal>ngx_master_process_cycle()</literal> function.
+NGINX configuration, creates cycles, and starts and controls child processes.
-Master process does not have any I/O and responds only to signals.
+It does not perform any I/O and responds only to signals.
-It reads configuration, creates cycles, starts and controls child processes
+Its cycle function is <literal>ngx_master_process_cycle()</literal>.
 </para>
 </listitem>
 <listitem>
 <para>
-<literal>NGX_PROCESS_WORKER</literal> — the worker process runs the
+<literal>NGX_PROCESS_WORKER</literal> — The worker process, which handles client
-<literal>ngx_worker_process_cycle()</literal> function.
+connections.
-Worker processes are started by master and handle client connections.
+It is started by the master process and responds to its signals and channel
-They also respond to signals and channel commands, sent from master
+commands as well.
-</para>
+Its cycle function is <literal>ngx_worker_process_cycle()</literal>.
+There can be multiple worker processes, as configured by the
+<literal>worker_processes</literal> directive.
-</listitem>
+</para>
-<listitem>
+</listitem>
-<para>
+<listitem>
-<literal>NGX_PROCESS_SINGLE</literal> — single process is the only type
-of processes which exist in the <literal>master_process off</literal> mode.
+<para>
-The cycle function for this process is
+<literal>NGX_PROCESS_SINGLE</literal> — The single process, which exists only in
-<literal>ngx_single_process_cycle()</literal>.
+<literal>master_process off</literal> mode, and is the only process running in
-This process creates cycles and handles client connections
+that mode.
-</para>
+It creates cycles (like the master process does) and handles client connections
+(like the worker process does).
+Its cycle function is <literal>ngx_single_process_cycle()</literal>.
-</listitem>
+</para>
-<listitem>
+</listitem>
-<para>
+<listitem>
-<literal>NGX_PROCESS_HELPER</literal> — currently, there are two types of
-helper processes: cache manager and cache loader.
+<para>
-Both of them share the same cycle function
+<literal>NGX_PROCESS_HELPER</literal> — The helper process, of which currently
+there are two types: cache manager and cache loader.
+The cycle function for both is
 <literal>ngx_cache_manager_process_cycle()</literal>.
 </para>
+</listitem>
-</listitem>
+</list>
-</list>
+<para>
-<para>
+The nginx processes handle the following signals:
-All nginx processes handle the following signals:
+</para>
-</para>
+<list type="bullet">
-<list type="bullet">
+<listitem>
-<listitem>
+<para>
-<para>
+<literal>NGX_SHUTDOWN_SIGNAL</literal> (<literal>SIGQUIT</literal> on most
-<literal>NGX_SHUTDOWN_SIGNAL</literal> (<literal>SIGQUIT</literal>) — graceful
+systems) — Gracefully shutdown.
-shutdown.
+Upon receiving this signal, the master process sends a shutdown signal to all
-Upon receiving this signal master process sends shutdown signal to all child
+child processes.
-processes.
+When no child processes are left, the master destroys the cycle pool and exits.
-When no child processes are left, master destroys cycle pool and exits.
+When a worker process receives this signal, it closes all listening sockets and
-A worker process which received this signal, closes all listening sockets and
+waits until there are no non-cancelable events scheduled, then destroys the
-waits until timeout tree becomes empty, then destroys cycle pool and exits.
+cycle pool and exits.
-A cache manager process exits right after receiving this signal.
+When the cache manager or the cache loader process receives this signal, it
-The variable <literal>ngx_quit</literal> is set to one after receiving this
+exits immediately.
-signal and immediately reset after being processed.
+The <literal>ngx_quit</literal> variable is set to <literal>1</literal> when a
-The variable <literal>ngx_exiting</literal> is set to one when worker process
+process receives this signal, and is immediately reset after being processed.
-is in shutdown state
+The <literal>ngx_exiting</literal> variable is set to <literal>1</literal> while
-</para>
+a worker process is in the shutdown state.
+</para>
 </listitem>
 <listitem>
 <para>
-<literal>NGX_TERMINATE_SIGNAL</literal> (<literal>SIGTERM</literal>) -
+<literal>NGX_TERMINATE_SIGNAL</literal> (<literal>SIGTERM</literal> on most
-terminate.
+systems) — Terminate.
-Upon receiving this signal master process sends terminate signal to all child
+Upon receiving this signal, the master process sends a terminate signal to all
-processes.
+child processes.
-If child processes do not exit in 1 second, they are killed with the
+If a child process does not exit within 1 second, the master process sends the
-<literal>SIGKILL</literal> signal.
+<literal>SIGKILL</literal> signal to kill it.
-When no child processes are left, master process destroys cycle pool and exits.
+When no child processes are left, the master process destroys the cycle pool and
-A worker or cache manager process which received this signal destroys cycle
+exits.
-pool and exits.
+When a worker process, the cache manager process or the cache loader process
-The variable <literal>ngx_terminate</literal> is set to one after receiving
+receives this signal, it destroys the cycle pool and exits.
-this signal
+The variable <literal>ngx_terminate</literal> is set to <literal>1</literal>
-</para>
+when this signal is received.
+</para>
 </listitem>
 <listitem>
 <para>
-<literal>NGX_NOACCEPT_SIGNAL</literal> (<literal>SIGWINCH</literal>)
+<literal>NGX_NOACCEPT_SIGNAL</literal> (<literal>SIGWINCH</literal> on most
-- gracefully shut down worker processes
+systems) - Shut down all worker and helper processes.
-</para>
+Upon receiving this signal, the master process shuts down its child processes.
+If a previously started new nginx binary exits, the child processes of the old
+master are started again.
-</listitem>
+When a worker process receives this signal, it shuts down in debug mode
+set by the <literal>debug_points</literal> directive.
-<listitem>
+</para>
-<para>
-<literal>NGX_RECONFIGURE_SIGNAL</literal> (<literal>SIGHUP</literal>) -
+</listitem>
-reconfigure.
-Upon receiving this signal master process creates a new cycle from
+<listitem>
-configuration file.
-If the new cycle was created successfully, the old cycle is deleted and new
+<para>
+<literal>NGX_RECONFIGURE_SIGNAL</literal> (<literal>SIGHUP</literal> on most
+systems) - Reconfigure.
+Upon receiving this signal, the master process re-reads the configuration and
+creates a new cycle based on it.
+If the new cycle is created successfully, the old cycle is deleted and new
 child processes are started.
-Meanwhile, the old processes receive the shutdown signal.
+Meanwhile, the old child processes receive the
-In single-process mode, nginx creates a new cycle as well, but keeps the old
+<literal>NGX_SHUTDOWN_SIGNAL</literal> signal.
-one until all clients, tied to the old cycle, are gone.
+In single-process mode, nginx creates a new cycle, but keeps the old one until
-Worker and helper processes ignore this signal
+there are no longer clients with active connections tied to it.
-</para>
+The worker and helper processes ignore this signal.
+</para>
 </listitem>
 <listitem>
 <para>
-<literal>NGX_REOPEN_SIGNAL</literal> (<literal>SIGUSR1</literal>) — reopen
+<literal>NGX_REOPEN_SIGNAL</literal> (<literal>SIGUSR1</literal> on most
-files.
+systems) — Reopen files.
-Master process passes this signal to workers.
+The master process sends this signal to workers, which reopen all
-Worker processes reopen all <literal>open_files</literal> from the cycle
+<literal>open_files</literal> related to the cycle.
 </para>
+</listitem>
-</listitem>
+<listitem>
-<listitem>
+<para>
-<para>
+<literal>NGX_CHANGEBIN_SIGNAL</literal> (<literal>SIGUSR2</literal> on most
-<literal>NGX_CHANGEBIN_SIGNAL</literal> (<literal>SIGUSR2</literal>) — change
+systems) — Change the nginx binary.
-nginx binary.
+The master process starts a new nginx binary and passes in a list of all listen
-Master process starts a new nginx binary and passes there a list of all listen
 sockets.
-The list is passed in the environment variable <literal>“NGINX”</literal> in
+The text-format list, passed in the <literal>“NGINX”</literal> environment
-text format, where descriptor numbers separated with semicolons.
+variable, consists of descriptor numbers separated with semicolons.
-A new nginx instance reads that variable and adds the sockets to its init
+The new nginx binary reads the <literal>“NGINX”</literal> variable and adds the
-cycle.
+sockets to its init cycle.
-Other processes ignore this signal
+Other processes ignore this signal.
 </para>
 </listitem>
 </list>
 <para>
 While all nginx worker processes are able to receive and properly handle POSIX
-signals, master process normally does not pass any signals to workers and
+signals, the master process does not use the standard <literal>kill()</literal>
-helpers with the standard <literal>kill()</literal> syscall.
+syscall to pass signals to workers and helpers.
-Instead, nginx uses inter-process channels which allow sending messages between
+Instead, nginx uses inter-process socket pairs which allow sending messages
-all nginx processes.
+between all nginx processes.
-Currently, however, messages are only sent from master to its children.
+Currently, however, messages are only sent from the master to its children.
-Those messages carry the same signals.
+The messages carry the standard signals.
-The channels are socketpairs with their ends in different processes.
-</para>
-<para>
-When running nginx binary, several values can be specified next to
-<literal>-s</literal> parameter.
-Those values are <literal>stop</literal>, <literal>quit</literal>,
-<literal>reopen</literal>, <literal>reload</literal>.
-They are converted to signals <literal>NGX_TERMINATE_SIGNAL</literal>,
-<literal>NGX_SHUTDOWN_SIGNAL</literal>, <literal>NGX_REOPEN_SIGNAL</literal>
-and <literal>NGX_RECONFIGURE_SIGNAL</literal> and sent to the nginx master
-process, whose pid is read from nginx pid file.
 </para>
 </section>
 <section name="Threads" id="threads">
 <para>
-It is possible to offload tasks that would otherwise block nginx worker process
+It is possible to offload into a separate thread tasks that would otherwise
-into a separate thread.
+block the nginx worker process.
-For example, nginx may be configured to use threads to perform
+For example, nginx can be configured to use threads to perform
 <link doc="../http/ngx_http_core_module.xml" id="aio">file I/O</link>.
-Another example is using a library that doesn't have asynchronous interface
+Another use case is a library that doesn't have asynchronous interface
 and thus cannot be normally used with nginx.
-Keep in mind that threads interface is a helper for existing asynchronous
+Keep in mind that the threads interface is a helper for the existing
-approach in processing client connections, and by no means a replacement.
+asynchronous approach to processing client connections, and by no means
-</para>
+intended as a replacement.
+</para>
-<para>
-To deal with synchronization the following wrappers over pthreads primitives
+<para>
-are available:
+To deal with synchronization, the following wrappers over
-<programlisting>
+<literal>pthreads</literal> primitives are available:
-typedef pthread_mutex_t  ngx_thread_mutex_t;
+<list type="bullet">
-ngx_int_t ngx_thread_mutex_create(ngx_thread_mutex_t *mtx, ngx_log_t *log);
-ngx_int_t ngx_thread_mutex_destroy(ngx_thread_mutex_t *mtx, ngx_log_t *log);
+<listitem>
-ngx_int_t ngx_thread_mutex_lock(ngx_thread_mutex_t *mtx, ngx_log_t *log);
+<literal>typedef pthread_mutex_t  ngx_thread_mutex_t;</literal>
-ngx_int_t ngx_thread_mutex_unlock(ngx_thread_mutex_t *mtx, ngx_log_t *log);
+<list type="bullet">
-typedef pthread_cond_t  ngx_thread_cond_t;
+<listitem>
-ngx_int_t ngx_thread_cond_create(ngx_thread_cond_t *cond, ngx_log_t *log);
+<literal>ngx_int_t
-ngx_int_t ngx_thread_cond_destroy(ngx_thread_cond_t *cond, ngx_log_t *log);
+ngx_thread_mutex_create(ngx_thread_mutex_t *mtx, ngx_log_t *log);</literal>
-ngx_int_t ngx_thread_cond_signal(ngx_thread_cond_t *cond, ngx_log_t *log);
+</listitem>
-ngx_int_t ngx_thread_cond_wait(ngx_thread_cond_t *cond, ngx_thread_mutex_t *mtx,
-ngx_log_t *log);
+<listitem>
-</programlisting>
+<literal>ngx_int_t
+ngx_thread_mutex_destroy(ngx_thread_mutex_t *mtx, ngx_log_t *log);</literal>
+</listitem>
+<listitem>
+<literal>ngx_int_t
+ngx_thread_mutex_lock(ngx_thread_mutex_t *mtx, ngx_log_t *log);</literal>
+</listitem>
+<listitem>
+<literal>ngx_int_t
+ngx_thread_mutex_unlock(ngx_thread_mutex_t *mtx, ngx_log_t *log);</literal>
+</listitem>
+</list>
+</listitem>
+<listitem>
+<literal>typedef pthread_cond_t  ngx_thread_cond_t;</literal>
+<list type="bullet">
+<listitem>
+<literal>ngx_int_t
+ngx_thread_cond_create(ngx_thread_cond_t *cond, ngx_log_t *log);</literal>
+</listitem>
+<listitem>
+<literal>ngx_int_t
+ngx_thread_cond_destroy(ngx_thread_cond_t *cond, ngx_log_t *log);</literal>
+</listitem>
+<listitem>
+<literal>ngx_int_t
+ngx_thread_cond_signal(ngx_thread_cond_t *cond, ngx_log_t *log);</literal>
+</listitem>
+<listitem>
+<literal>ngx_int_t
+ngx_thread_cond_wait(ngx_thread_cond_t *cond, ngx_thread_mutex_t *mtx,
+ngx_log_t *log);</literal>
+</listitem>
+</list>
+</listitem>
+</list>
 </para>
 <para>
 Instead of creating a new thread for each task, nginx implements
 a <link doc="../ngx_core_module.xml" id="thread_pool"/> strategy.
-Multiple thread pools may be configured intended for different purposes
+Multiple thread pools may be configured for different purposes
 (for example, performing I/O on different sets of disks).
-Each thread pool is created on start and contains a limited number of threads
+Each thread pool is created at startup and contains a limited number of threads
 that process a queue of tasks.
 When a task is completed, a predefined completion handler is called.
 </para>
 <para>
 The <literal>src/core/ngx_thread_pool.h</literal> header file contains
-corresponding definitions:
+relevant definitions:
 <programlisting>
 struct ngx_thread_task_s {
 ngx_thread_task_t   *next;
 ngx_uint_t           id;
 void                *ctx;
 ngx_thread_task_t *ngx_thread_task_alloc(ngx_pool_t *pool, size_t size);
 ngx_int_t ngx_thread_task_post(ngx_thread_pool_t *tp, ngx_thread_task_t *task);
 </programlisting>
 At configuration time, a module willing to use threads has to obtain a
-reference to thread pool by calling
+reference to a thread pool by calling
-<literal>ngx_thread_pool_add(cf, name)</literal> which will either create a
+<literal>ngx_thread_pool_add(cf, name)</literal>, which either creates a
-new thread pool with given <literal>name</literal> or return a reference
+new thread pool with the given <literal>name</literal> or returns a reference
-to an existing one if a pool with such name already exists.
+to the pool with that name if it already exists.
 </para>
 <para>
-At runtime, the <literal>ngx_thread_task_post(tp, task)</literal> function
+To add a <literal>task</literal> into a queue of a specified thread pool
-is used to add a <literal>task</literal> into a queue of a thread pool
+<literal>tp</literal> at runtime, use the
-<literal>tp</literal>.
+<literal>ngx_thread_task_post(tp, task)</literal> function.
-The <literal>ngx_thread_task_t</literal> structure contains all necessary
+To execute a function in a thread, pass parameters and setup a completion
-to execute user function in thread, pass parameters and setup completion
+handler using the <literal>ngx_thread_task_t</literal> structure:
-handler:
 <programlisting>
 typedef struct {
 int    foo;
 } my_thread_ctx_t;
 <section name="Modules" id="Modules">
 <section name="Adding new modules" id="adding_new_modules">
 <para>
-The standalone nginx module resides in a separate directory that contains
+Each standalone nginx module resides in a separate directory that contains
 at least two files:
-<literal>config</literal> and a file with the module source.
+<literal>config</literal> and a file with the module source code.
-The first file contains all information needed for nginx to integrate
+The <literal>config</literal> file contains all information needed for nginx to
-the module, for example:
+integrate the module, for example:
 <programlisting>
 ngx_module_type=CORE
 ngx_module_name=ngx_foo_module
 ngx_module_srcs="$ngx_addon_dir/ngx_foo_module.c"
 . auto/module
 ngx_addon_name=$ngx_module_name
 </programlisting>
-The file is a POSIX shell script and it can set (or access) the
+The <literal>config</literal> file is a POSIX shell script that can set
-following variables:
+and access the following variables:
 <list type="bullet">
 <listitem>
-<literal>ngx_module_type</literal> — the type of module to build.
+<literal>ngx_module_type</literal> — Type of module to build.
-Possible options are <literal>CORE</literal>, <literal>HTTP</literal>,
+Possible values are <literal>CORE</literal>, <literal>HTTP</literal>,
 <literal>HTTP_FILTER</literal>, <literal>HTTP_INIT_FILTER</literal>,
 <literal>HTTP_AUX_FILTER</literal>, <literal>MAIL</literal>,
-<literal>STREAM</literal>, or <literal>MISC</literal>
+<literal>STREAM</literal>, or <literal>MISC</literal>.
 </listitem>
 <listitem>
-<literal>ngx_module_name</literal> — the name of the module.
+<literal>ngx_module_name</literal> — Module names.
-A whitespace separated values list is accepted and may be used to build
+To build multiple modules from a set of source files, specify a
-multiple modules from a single set of source files.
+whitespace-separated list of names.
-The first name indicates the name of the output binary for a dynamic module.
+The first name indicates the name of the output binary for the dynamic module.
-The names in this list should match the names used in the module.
+The names in the list must match the names used in the source code.
 </listitem>
 <listitem>
-<literal>ngx_addon_name</literal> — supplies the name of the module in the
+<literal>ngx_addon_name</literal> — Name of the module as it appears in output
-console output text of the configure script.
+on the console from the configure script.
 </listitem>
 <listitem>
-<literal>ngx_module_srcs</literal> — a whitespace separated list of source
+<literal>ngx_module_srcs</literal> — 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
+The <literal>$ngx_addon_dir</literal> variable can be used to represent the path
-module source.
+to the module directory.
 </listitem>
 <listitem>
-<literal>ngx_module_incs</literal> — include paths required to build the module
+<literal>ngx_module_incs</literal> — Include paths required to build the module
 </listitem>
 <listitem>
-<literal>ngx_module_deps</literal> — a list of module's header files.
+<literal>ngx_module_deps</literal> — Whitespace-separated list of the module's
-</listitem>
+dependencies.
+Usually, it is the list of header files.
-<listitem>
+</listitem>
-<literal>ngx_module_libs</literal> — a list of libraries to link with the
-module.
+<listitem>
-For example, libpthread would be linked using
+<literal>ngx_module_libs</literal> — Whitespace-separated list of libraries to
-<literal>ngx_module_libs=-lpthread</literal>.
+link with the module.
+For example, use <literal>ngx_module_libs=-lpthread</literal> to link
+<literal>libpthread</literal> library.
 The following macros can be used to link against the same libraries as
 nginx:
 <literal>LIBXSLT</literal>, <literal>LIBGD</literal>, <literal>GEOIP</literal>,
 <literal>PCRE</literal>, <literal>OPENSSL</literal>, <literal>MD5</literal>,
-<literal>SHA1</literal>, <literal>ZLIB</literal>, and <literal>PERL</literal>
+<literal>SHA1</literal>, <literal>ZLIB</literal>, and <literal>PERL</literal>.
 </listitem>
 <listitem>
-<literal>ngx_module_link</literal> — set by the build system to
+<literal>ngx_module_link</literal> — Variable set by the build system to
 <literal>DYNAMIC</literal> for a dynamic module or <literal>ADDON</literal>
-for a static module and used to perform different actions depending on
+for a static module and used to determine different actions to perform
-linking type.
+depending on linking type.
 </listitem>
 <listitem>
-<literal>ngx_module_order</literal> — sets the load order for the module which
+<literal>ngx_module_order</literal> — Load order for the module;
-is useful for <literal>HTTP_FILTER</literal> and
+useful for the <literal>HTTP_FILTER</literal> and
 <literal>HTTP_AUX_FILTER</literal> module types.
-The order is stored in a reverse list.
+The format for this option is a whitespace-separated list of modules.
+All modules in the list following the current module's name end up after it in
-<para>
+the global list of modules, which sets up the order for modules initialization.
-The <literal>ngx_http_copy_filter_module</literal> is near the bottom of the
+For filter modules later initialization means earlier execution.
-list so is one of the first to be executed.
-This reads the data for other filters.
+<para>
-Near the top of the list is <literal>ngx_http_write_filter_module</literal>
+The following modules are typically used as references.
-which writes the data out and is one of the last to be executed.
+The <literal>ngx_http_copy_filter_module</literal> reads the data for other
-</para>
+filter modules and is placed near the bottom of the list so that it is one of
+the first to be executed.
-<para>
+The <literal>ngx_http_write_filter_module</literal> writes the data to the
-The format for this option is typically the current module’s name followed by
+client socket and is placed near the top of the list, and is the last to be
-a whitespace separated list of modules to insert before, and therefore execute
+executed.
-after.
+</para>
-The module will be inserted before the last module in the list that is found
-to be currently loaded.
+<para>
-</para>
+By default, filter modules are placed before the
+<literal>ngx_http_copy_filter</literal> in the module list so that the filter
-<para>
+handler is executed after the copy filter handler.
-By default for filter modules this is set to
+For other module types the default is the empty string.
-“<literal>ngx_http_copy_filter</literal>” which will insert the module before
+</para>
-the copy filter in the list and therefore will execute after the copy filter.
-For other module types the default is empty.
+</listitem>
-</para>
+</list>
-</listitem>
+To compile a module into nginx statically, use the
-</list>
+<literal>--add-module=/path/to/module</literal> argument to the configure
+script.
-A module can be added to nginx by means of the configure script using
+To compile a module for later dynamic loading into nginx, use the
-<literal>--add-module=/path/to/module</literal> for static compilation and
+<literal>--add-dynamic-module=/path/to/module</literal> argument.
-<literal>--add-dynamic-module=/path/to/module</literal> for dynamic compilation.
 </para>
 </section>
-<section name="Core modules" id="core_modules">
+<section name="Core Modules" id="core_modules">
 <para>
-Modules are building blocks of nginx, and most of its functionality is
+Modules are the building blocks of nginx, and most of its functionality is
 implemented as modules.
-The module source file must contain a global variable of
+The module source file must contain a global variable of type
-<literal>ngx_module_t</literal> type which is defined as follows:
+<literal>ngx_module_t</literal>, which is defined as follows:
 <programlisting>
 struct ngx_module_s {
 /* private part is omitted */
 void                (*exit_master)(ngx_cycle_t *cycle);
 /* stubs for future extensions are omitted */
 };
 </programlisting>
-The omitted private part includes module version, signature and is filled
+The omitted private part includes the module version and a signature and is
-using the predefined macro <literal>NGX_MODULE_V1</literal>.
+filled using the predefined macro <literal>NGX_MODULE_V1</literal>.
 </para>
 <para>
 Each module keeps its private data in the <literal>ctx</literal> field,
-recognizes specific configuration directives, specified in the
+recognizes the configuration directives, specified in the
-<literal>commands</literal> array, and may be invoked at certain stages of
+<literal>commands</literal> array, and can be invoked at certain stages of
 nginx lifecycle.
 The module lifecycle consists of the following events:
 <list type="bullet">
 <listitem>
 Configuration directive handlers are called as they appear
-in configuration files in the context of the master process
+in configuration files in the context of the master process.
 </listitem>
 <listitem>
-The <literal>init_module</literal> handler is called in the context of
+After the configuration is parsed successfully, <literal>init_module</literal>
-the master process after the configuration is parsed successfully
+handler is called in the context of the master process.
-</listitem>
+The <literal>init_module</literal> handler is called in the master process each
+time a configuration is loaded.
-<listitem>
+</listitem>
-The master process creates worker process(es) and
-<literal>init_process</literal> handler is called in each of them
+<listitem>
-</listitem>
+The master process creates one or more worker processes and the
+<literal>init_process</literal> handler is called in each of them.
-<listitem>
+</listitem>
-When a worker process receives the shutdown command from master, it invokes
-the <literal>exit_process</literal> handler
+<listitem>
+When a worker process receives the shutdown or terminate command from the
+master, it invokes the <literal>exit_process</literal> handler.
 </listitem>
 <listitem>
 The master process calls the <literal>exit_master</literal> handler before
 exiting.
 </listitem>
 </list>
-<note>
+Because threads are used in nginx only as a supplementary I/O facility with its
-<literal>init_module</literal> handler may be called multiple times
+own API, <literal>init_thread</literal> and <literal>exit_thread</literal>
-in the master process if the configuration reload is requested.
+handlers are not currently called.
-</note>
+There is also no <literal>init_master</literal> handler, because it would be
+unnecessary overhead.
-The <literal>init_master</literal>, <literal>init_thread</literal> and
+</para>
-<literal>exit_thread</literal> handlers are not implemented at the moment;
-Threads in nginx are only used as supplementary I/O facility with its own
+<para>
-API and <literal>init_master</literal> handler looks unnecessary.
+The module <literal>type</literal> defines exactly what is stored in the
-</para>
-<para>
-The module <literal>type</literal> defines what exactly is stored in the
 <literal>ctx</literal> field.
-There are several types of modules:
+Its value is one of the following types:
 <list type="bullet">
 <listitem><literal>NGX_CORE_MODULE</literal></listitem>
 <listitem><literal>NGX_EVENT_MODULE</literal></listitem>
 <listitem><literal>NGX_HTTP_MODULE</literal></listitem>
 <listitem><literal>NGX_MAIL_MODULE</literal></listitem>
 <listitem><literal>NGX_STREAM_MODULE</literal></listitem>
 </list>
 The <literal>NGX_CORE_MODULE</literal> is the most basic and thus the most
-generic and most low-level type of module. Other module types are implemented
+generic and most low-level type of module.
-on top of it and provide more convenient way to deal with corresponding
+The other module types are implemented on top of it and provide a more
-problem domains, like handling events or http requests.
+convenient way to deal with corresponding domains, like handling events or HTTP
-</para>
+requests.
+</para>
-<para>
-The examples of core modules are <literal>ngx_core_module</literal>,
+<para>
+The set of core modules includes <literal>ngx_core_module</literal>,
 <literal>ngx_errlog_module</literal>, <literal>ngx_regex_module</literal>,
-<literal>ngx_thread_pool_module</literal>,
+<literal>ngx_thread_pool_module</literal> and
-<literal>ngx_openssl_module</literal>
+<literal>ngx_openssl_module</literal> modules.
-modules and, of course, http, stream, mail and event modules itself.
+The HTTP module, the stream module, the mail module and event modules are core
+modules too.
 The context of a core module is defined as:
 <programlisting>
 typedef struct {
 ngx_str_t             name;
 void               *(*create_conf)(ngx_cycle_t *cycle);
 char               *(*init_conf)(ngx_cycle_t *cycle, void *conf);
 } ngx_core_module_t;
 </programlisting>
-where the <literal>name</literal> is a string with a module name for
+where the <literal>name</literal> is a module name string,
-convenience, <literal>create_conf</literal> and <literal>init_conf</literal>
+<literal>create_conf</literal> and <literal>init_conf</literal>
 are pointers to functions that create and initialize module configuration
-correspondingly.
+respectively.
-For core modules, nginx will call <literal>create_conf</literal> before parsing
+For core modules, nginx calls <literal>create_conf</literal> before parsing
 a new configuration and <literal>init_conf</literal> after all configuration
-was parsed successfully.
+is parsed successfully.
 The typical <literal>create_conf</literal> function allocates memory for the
 configuration and sets default values.
-The <literal>init_conf</literal> deals with known configuration and thus may
+</para>
-perform sanity checks and complete initialization.
-</para>
+<para>
+For example, a simplistic module called <literal>ngx_foo_module</literal> might
-<para>
+look like this:
-For example, the simplistic <literal>ngx_foo_module</literal> can look like
-this:
 <programlisting>
 /*
 * Copyright (C) Author.
 */
 </para>
 </section>
-<section name="Configuration directives" id="config_directives">
+<section name="Configuration Directives" id="config_directives">
 <para>
-The <literal>ngx_command_t</literal> describes single configuration directive.
+The <literal>ngx_command_t</literal> type defines a single configuration
-Each module, supporting configuration, provides an array of such specifications
+directive.
+Each module that supports configuration provides an array of such structures
 that describe how to process arguments and what handlers to call:
 <programlisting>
+typedef struct ngx_command_s  ngx_command_t;
 struct ngx_command_s {
 ngx_str_t             name;
 ngx_uint_t            type;
 char               *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf);
 ngx_uint_t            conf;
 ngx_uint_t            offset;
 void                 *post;
 };
 </programlisting>
-The array should be terminated by a special value
+Terminate the array with the special value <literal>ngx_null_command</literal>.
-“<literal>ngx_null_command</literal>”.
+The <literal>name</literal> is the name of a directive as it appears
-The <literal>name</literal> is the literal name of a directive, as it appears
+in the configuration file, for example "worker_processes" or "listen".
-in configuration file, for example “<literal>worker_processes</literal>” or
+The <literal>type</literal> is a bit-field of flags that specify the number of
-“<literal>listen</literal>”.
+arguments the directive takes, its type, and the context in which it appears.
-The <literal>type</literal> is a bitfield that controls number of arguments,
+The flags are:
-command type and other properties using corresponding flags.
-Arguments flags:
+<list type="bullet">
-<list type="bullet">
+<listitem>
+<literal>NGX_CONF_NOARGS</literal> — Directive takes no arguments.
-<listitem>
+</listitem>
-<literal>NGX_CONF_NOARGS</literal> — directive without arguments
-</listitem>
+<listitem>
+<literal>NGX_CONF_1MORE</literal> — Directive takes one or more arguments.
-<listitem><literal>NGX_CONF_1MORE</literal> — one required argument</listitem>
+</listitem>
-<listitem><literal>NGX_CONF_2MORE</literal> — two required arguments</listitem>
+<listitem>
+<literal>NGX_CONF_2MORE</literal> — Directive takes two or more arguments.
-<listitem>
+</listitem>
-<literal>NGX_CONF_TAKE1..7</literal> — exactly 1..7 arguments
-</listitem>
+<listitem>
+<literal>NGX_CONF_TAKE1</literal>..<literal>NGX_CONF_TAKE7</literal> —
-<listitem>
+Directive takes exactly the indicated number of arguments.
-<literal>NGX_CONF_TAKE12, 13, 23, 123, 1234</literal> — one or two arguments,
+</listitem>
-or other combinations
-</listitem>
+<listitem>
+<literal>NGX_CONF_TAKE12</literal>, <literal>NGX_CONF_TAKE13</literal>,
-</list>
+<literal>NGX_CONF_TAKE23</literal>, <literal>NGX_CONF_TAKE123</literal>,
+<literal>NGX_CONF_TAKE1234</literal> — Directive may take different number of
-Directive types:
+arguments.
+Options are limited to the given numbers.
-<list type="bullet">
+For example, <literal>NGX_CONF_TAKE12</literal> means it takes one or two
+arguments.
-<listitem>
+</listitem>
-<literal>NGX_CONF_BLOCK</literal> — the directive is a block, i.e. it may
-contain other directives in curly braces, or even implement its own parser
+</list>
-to handle contents inside.
-</listitem>
+The flags for directive types are:
-<listitem>
+<list type="bullet">
-<literal>NGX_CONF_FLAG</literal> — the directive value is a flag, a boolean
-value represented by “<literal>on</literal>” or “<literal>off</literal>”
+<listitem>
-strings.
+<literal>NGX_CONF_BLOCK</literal> — Directive is a block, that is, it can
-</listitem>
+contain other directives within its opening and closing curly braces, or even
-</list>
+implement its own parser to handle contents inside.
+</listitem>
-Context of a directive defines where in the configuration it may appear
-and how to access module context to store corresponding values:
+<listitem>
-<list type="bullet">
+<literal>NGX_CONF_FLAG</literal> — Directive takes a boolean value, either
+<literal>on</literal> or <literal>off</literal>.
-<listitem>
+</listitem>
-<literal>NGX_MAIN_CONF</literal> — top level configuration
-</listitem>
+</list>
-<listitem>
+A directive's context defines where it may appear in the configuration:
-<literal>NGX_HTTP_MAIN_CONF</literal> — in the http block
-</listitem>
+<list type="bullet">
 <listitem>
-<literal>NGX_HTTP_SRV_CONF</literal> — in the http server block
+<literal>NGX_MAIN_CONF</literal> — In the top level context.
 </listitem>
 <listitem>
-<literal>NGX_HTTP_LOC_CONF</literal> — in the http location
+<literal>NGX_HTTP_MAIN_CONF</literal> — In the <literal>http</literal> block.
 </listitem>
 <listitem>
-<literal>NGX_HTTP_UPS_CONF</literal> — in the http upstream block
+<literal>NGX_HTTP_SRV_CONF</literal> — In a <literal>server</literal> block
-</listitem>
+within the <literal>http</literal> block.
+</listitem>
-<listitem>
-<literal>NGX_HTTP_SIF_CONF</literal> — in the http server “if”
+<listitem>
-</listitem>
+<literal>NGX_HTTP_LOC_CONF</literal> — In a <literal>location</literal> block
+within the <literal>http</literal> block.
-<listitem>
+</listitem>
-<literal>NGX_HTTP_LIF_CONF</literal> — in the http location “if”
-</listitem>
+<listitem>
+<literal>NGX_HTTP_UPS_CONF</literal> — In an <literal>upstream</literal> block
-<listitem>
+within the <literal>http</literal> block.
-<literal>NGX_HTTP_LMT_CONF</literal> — in the http “limit_except”
+</listitem>
-</listitem>
+<listitem>
-<listitem>
+<literal>NGX_HTTP_SIF_CONF</literal> — In an <literal>if</literal> block within
-<literal>NGX_STREAM_MAIN_CONF</literal> — in the stream block
+a <literal>server</literal> block in the <literal>http</literal> block.
 </listitem>
 <listitem>
-<literal>NGX_STREAM_SRV_CONF</literal> — in the stream server block
+<literal>NGX_HTTP_LIF_CONF</literal> — In an <literal>if</literal> block within
-</listitem>
+a <literal>location</literal> block in the <literal>http</literal> block.
+</listitem>
-<listitem>
-<literal>NGX_STREAM_UPS_CONF</literal> — in the stream upstream block
+<listitem>
-</listitem>
+<literal>NGX_HTTP_LMT_CONF</literal> — In a <literal>limit_except</literal>
+block within the <literal>http</literal> block.
-<listitem>
+</listitem>
-<literal>NGX_MAIL_MAIN_CONF</literal> — in the the mail block
-</listitem>
+<listitem>
+<literal>NGX_STREAM_MAIN_CONF</literal> — In the <literal>stream</literal>
-<listitem>
+block.
-<literal>NGX_MAIL_SRV_CONF</literal> — in the mail server block
+</listitem>
-</listitem>
+<listitem>
-<listitem>
+<literal>NGX_STREAM_SRV_CONF</literal> — In a <literal>server</literal> block
-<literal>NGX_EVENT_CONF</literal> — in the event block
+within the <literal>stream</literal> block.
 </listitem>
 <listitem>
-<literal>NGX_DIRECT_CONF</literal> — used by modules that don't
+<literal>NGX_STREAM_UPS_CONF</literal> — In an <literal>upstream</literal> block
-create a hierarchy of contexts and store module configuration directly in ctx
+within the <literal>stream</literal> block.
 </listitem>
-</list>
-The configuration parser uses this flags to throw an error in case of
+<listitem>
+<literal>NGX_MAIL_MAIN_CONF</literal> — In the <literal>mail</literal> block.
+</listitem>
+<listitem>
+<literal>NGX_MAIL_SRV_CONF</literal> — In a <literal>server</literal> block
+within the <literal>mail</literal> block.
+</listitem>
+<listitem>
+<literal>NGX_EVENT_CONF</literal> — In the <literal>event</literal> block.
+</listitem>
+<listitem>
+<literal>NGX_DIRECT_CONF</literal> — Used by modules that don't
+create a hierarchy of contexts and only have one global configuration.
+This configuration is passed to the handler as the <literal>conf</literal>
+argument.
+</listitem>
+</list>
+The configuration parser uses these flags to throw an error in case of
 a misplaced directive and calls directive handlers supplied with a proper
-configuration pointer, so that same directives in different locations could
+configuration pointer, so that the same directives in different locations can
 store their values in distinct places.
 </para>
 <para>
 The <literal>set</literal> field defines a handler that processes a directive
-and stores parsed values into corresponding configuration.
+and stores parsed values into the corresponding configuration.
-Nginx offers a convenient set of functions that perform common conversions:
+There's a number of functions that perform common conversions:
 <list type="bullet">
 <listitem>
-<literal>ngx_conf_set_flag_slot</literal> — converts literal
+<literal>ngx_conf_set_flag_slot</literal> — Converts the literal strings
-“<literal>on</literal>” or “<literal>off</literal>” strings into
+<literal>on</literal> and <literal>off</literal> into an
-<literal>ngx_flag_t</literal> type with values 1 or 0
+<literal>ngx_flag_t</literal> value with values 1 or 0, respectively.
 </listitem>
 <listitem>
-<literal>ngx_conf_set_str_slot</literal> — stores string as a value of the
+<literal>ngx_conf_set_str_slot</literal> — Stores a string as a value of the
-<literal>ngx_str_t</literal> type
+<literal>ngx_str_t</literal> type.
 </listitem>
 <listitem>
-<literal>ngx_conf_set_str_array_slot</literal> — appends
+<literal>ngx_conf_set_str_array_slot</literal> — Appends a value to an array
-<literal>ngx_array_t</literal> of <literal>ngx_str_t</literal> with a new value.
+<literal>ngx_array_t</literal> of strings <literal>ngx_str_t</literal>.
-The array is created if not yet exists
+The array is created if does not already exist.
 </listitem>
 <listitem>
-<literal>ngx_conf_set_keyval_slot</literal> — appends
+<literal>ngx_conf_set_keyval_slot</literal> — Appends a key-value pair to an
-<literal>ngx_array_t</literal> of <literal>ngx_keyval_t</literal> with
+array <literal>ngx_array_t</literal> of key-value pairs
-a new value, where key is the first string and value is second.
+<literal>ngx_keyval_t</literal>.
-The array is created if not yet exists
+The first string becomes the key and the second the value.
-</listitem>
+The array is created if it does not already exist.
+</listitem>
-<listitem>
-<literal>ngx_conf_set_num_slot</literal> — converts directive argument
+<listitem>
-to a <literal>ngx_int_t</literal> value
+<literal>ngx_conf_set_num_slot</literal> — Converts a directive's argument
-</listitem>
+to an <literal>ngx_int_t</literal> value.
+</listitem>
-<listitem>
-<literal>ngx_conf_set_size_slot</literal> — converts
+<listitem>
-<link doc="../syntax.xml">size</link> to <literal>size_t</literal> value
+<literal>ngx_conf_set_size_slot</literal> — Converts a
-in bytes
+<link doc="../syntax.xml">size</link> to a <literal>size_t</literal> value
-</listitem>
+expressed in bytes.
+</listitem>
-<listitem>
-<literal>ngx_conf_set_off_slot</literal> — converts
+<listitem>
-<link doc="../syntax.xml">offset</link> to <literal>off_t</literal> value
+<literal>ngx_conf_set_off_slot</literal> — Converts an
-in bytes
+<link doc="../syntax.xml">offset</link> to an <literal>off_t</literal> value
-</listitem>
+expressed in bytes.
+</listitem>
-<listitem>
-<literal>ngx_conf_set_msec_slot</literal> — converts
+<listitem>
-<link doc="../syntax.xml">time</link> to <literal>ngx_msec_t</literal> value
+<literal>ngx_conf_set_msec_slot</literal> — Converts a
-in milliseconds
+<link doc="../syntax.xml">time</link> to an <literal>ngx_msec_t</literal> value
-</listitem>
+expressed in milliseconds.
+</listitem>
-<listitem>
-<literal>ngx_conf_set_sec_slot</literal> — converts
+<listitem>
-<link doc="../syntax.xml">time</link> to <literal>time_t</literal> value
+<literal>ngx_conf_set_sec_slot</literal> — Converts a
-in seconds
+<link doc="../syntax.xml">time</link> to a <literal>time_t</literal> value
-</listitem>
+expressed in in seconds.
+</listitem>
-<listitem>
-<literal>ngx_conf_set_bufs_slot</literal> — converts two arguments
+<listitem>
-into <literal>ngx_bufs_t</literal> that holds <literal>ngx_int_t</literal>
+<literal>ngx_conf_set_bufs_slot</literal> — Converts the two supplied arguments
-number and <link doc="../syntax.xml">size</link> of buffers
+into an <literal>ngx_bufs_t</literal> object that holds the number and
-</listitem>
+<link doc="../syntax.xml">size</link> of buffers.
+</listitem>
-<listitem>
-<literal>ngx_conf_set_enum_slot</literal> — converts argument
+<listitem>
-into <literal>ngx_uint_t</literal> value.
+<literal>ngx_conf_set_enum_slot</literal> — Converts the supplied argument
+into an <literal>ngx_uint_t</literal> value.
 The null-terminated array of <literal>ngx_conf_enum_t</literal> passed in the
-<literal>post</literal> field defines acceptable strings and corresponding
+<literal>post</literal> field defines the acceptable strings and corresponding
-integer values
+integer values.
 </listitem>
 <listitem>
-<literal>ngx_conf_set_bitmask_slot</literal> — arguments are converted to
+<literal>ngx_conf_set_bitmask_slot</literal> — Converts the supplied arguments
-<literal>ngx_uint_t</literal> value and OR'ed with the resulting value,
+into an <literal>ngx_uint_t</literal> value.
-forming a bitmask.
+The mask values for each argument are ORed producing the result.
-The null-terminated array of <literal>ngx_conf_bitmask_t</literal> passed in
+The null-terminated array of <literal>ngx_conf_bitmask_t</literal> passed in the
-the <literal>post</literal> field defines acceptable strings and corresponding
+<literal>post</literal> field defines the acceptable strings and corresponding
-mask values
+mask values.
 </listitem>
 <listitem>
-<literal>set_path_slot</literal> — converts arguments to
+<literal>set_path_slot</literal> — Converts the supplied arguments to an
-<literal>ngx_path_t</literal> type and performs all required initializations.
+<literal>ngx_path_t</literal> value and performs all required initializations.
-See the
+For details, see the documentation for the
-<link doc="../http/ngx_http_proxy_module.xml" id="proxy_temp_path">proxy_temp_path</link>
+<link doc="../http/ngx_http_proxy_module.xml" id="proxy_temp_path">
-directive description for details
+proxy_temp_path</link> directive.
 </listitem>
 <listitem>
-<literal>set_access_slot</literal> — converts arguments to file permissions
+<literal>set_access_slot</literal> — Converts the supplied arguments to a file
-mask.
+permissions mask.
-See the
+For details, see the documentation for the
-<link doc="../http/ngx_http_proxy_module.xml" id="proxy_store_access">proxy_store_access</link>
+<link doc="../http/ngx_http_proxy_module.xml" id="proxy_store_access">
-directive description for details
+proxy_store_access</link> directive.
 </listitem>
 </list>
 </para>
 <para>
-The <literal>conf</literal> field defines which context is used to store
+The <literal>conf</literal> field defines which configuration structure is
-the value of the directive, or zero if contexts are not used.
+passed to the directory handler.
-Only simple core modules use configuration without context and set
+Core modules only have the global configuration and set
-<literal>NGX_DIRECT_CONF</literal> flag.
+<literal>NGX_DIRECT_CONF</literal> flag to access it.
-In real life, such modules like http or stream require more sophisticated
+Modules like HTTP, Stream or Mail create hierarchies of configurations.
-configuration that can be applied per-server or per-location, or even more
+For example, a module's configuration is created for <literal>server</literal>,
-precisely, in the context of the “<literal>if</literal>” directive or
+<literal>location</literal> and <literal>if</literal> scopes.
-some limit.
-In this modules, configuration structure is more complex.
+<list type="bullet">
-Please refer to corresponding modules description to understand how
+<listitem>
-they manage their configuration.
+<literal>NGX_HTTP_MAIN_CONF_OFFSET</literal> — Configuration for the
+<literal>http</literal> block.
-<list type="bullet">
+</listitem>
-<listitem>
-<literal>NGX_HTTP_MAIN_CONF_OFFSET</literal> — http block configuration
+<listitem>
-</listitem>
+<literal>NGX_HTTP_SRV_CONF_OFFSET</literal> — Configuration for a
+<literal>server</literal> block within the <literal>http</literal> block.
-<listitem>
+</listitem>
-<literal>NGX_HTTP_SRV_CONF_OFFSET</literal> — http server configuration
-</listitem>
+<listitem>
+<literal>NGX_HTTP_LOC_CONF_OFFSET</literal> — Configuration for a
-<listitem>
+<literal>location</literal> block within the <literal>http</literal>.
-<literal>NGX_HTTP_LOC_CONF_OFFSET</literal> — http location configuration
+</listitem>
-</listitem>
+<listitem>
-<listitem>
+<literal>NGX_STREAM_MAIN_CONF_OFFSET</literal> — Configuration for the
-<literal>NGX_STREAM_MAIN_CONF_OFFSET</literal> — stream block configuration
+<literal>stream</literal> block.
 </listitem>
 <listitem>
-<literal>NGX_STREAM_SRV_CONF_OFFSET</literal> — stream server configuration
+<literal>NGX_STREAM_SRV_CONF_OFFSET</literal> — Configuration for a
-</listitem>
+<literal>server</literal> block within the <literal>stream</literal> block.
+</listitem>
-<listitem>
-<literal>NGX_MAIL_MAIN_CONF_OFFSET</literal> — mail block configuration
+<listitem>
-</listitem>
+<literal>NGX_MAIL_MAIN_CONF_OFFSET</literal> — Configuration for the
+<literal>mail</literal> block.
-<listitem>
+</listitem>
-<literal>NGX_MAIL_SRV_CONF_OFFSET</literal> — mail server configuration
-</listitem>
+<listitem>
+<literal>NGX_MAIL_SRV_CONF_OFFSET</literal> — Configuration for a
-</list>
+<literal>server</literal> block within the <literal>mail</literal> block.
+</listitem>
-</para>
+</list>
-<para>
-The <literal>offset</literal> defines an offset of a field in a module
+</para>
-configuration structure that holds values of this particular directive.
-The typical use is to employ <literal>offsetof()</literal> macro.
+<para>
-</para>
+The <literal>offset</literal> defines the offset of a field in a module
+configuration structure that holds values for this particular directive.
-<para>
+The typical use is to employ the <literal>offsetof()</literal> macro.
-The <literal>post</literal> is a twofold field: it may be used to define
+</para>
-a handler to be called after main handler completed or to pass additional
-data to the main handler.
+<para>
-In the first case, <literal>ngx_conf_post_t</literal> structure needs to
+The <literal>post</literal> field has two purposes: it may be used to define
-be initialized with a pointer to handler, for example:
+a handler to be called after the main handler has completed, or to pass
+additional data to the main handler.
+In the first case, the <literal>ngx_conf_post_t</literal> structure needs to
+be initialized with a pointer to the handler, for example:
 <programlisting>
 static char *ngx_do_foo(ngx_conf_t *cf, void *post, void *data);
 static ngx_conf_post_t  ngx_foo_post = { ngx_do_foo };
 </programlisting>
 The <literal>post</literal> argument is the <literal>ngx_conf_post_t</literal>
-object itself, and the <literal>data</literal> is a pointer to value,
+object itself, and the <literal>data</literal> is a pointer to the value,
 converted from arguments by the main handler with the appropriate type.
 </para>
 </section>
 <section name="Connection" id="http_connection">
 <para>
-Each client HTTP connection runs through the following stages:
+Each HTTP client connection runs through the following stages:
 </para>
 <list type="bullet">
 <listitem>
 <literal>ngx_event_accept()</literal> accepts a client TCP connection.
 This handler is called in response to a read notification on a listen socket.
-A new <literal>ngx_connecton_t</literal> object is created at this stage.
+A new <literal>ngx_connecton_t</literal> object is created at this stage
-The object wraps the newly accepted client socket.
+to wrap the newly accepted client socket.
 Each nginx listener provides a handler to pass the new connection object to.
-For HTTP connections it's <literal>ngx_http_init_connection(c)</literal>
+For HTTP connections it's <literal>ngx_http_init_connection(c)</literal>.
 </listitem>
 <listitem>
 <literal>ngx_http_init_connection()</literal> performs early initialization of
-an HTTP connection.
+the HTTP connection.
 At this stage an <literal>ngx_http_connection_t</literal> object is created for
-the connection and its reference is stored in connection's
+the connection and its reference is stored in the connection's
 <literal>data</literal> field.
-Later it will be substituted with an HTTP request object.
+Later it will be replaced by an HTTP request object.
-PROXY protocol parser and SSL handshake are started at this stage as well
+A PROXY protocol parser and the SSL handshake are started at
-</listitem>
+this stage as well.
+</listitem>
-<listitem>
-<literal>ngx_http_wait_request_handler()</literal> is a read event handler, that
+<listitem>
-is called when data is available in the client socket.
+<literal>ngx_http_wait_request_handler()</literal> read event handler
+is called when data is available on the client socket.
 At this stage an HTTP request object <literal>ngx_http_request_t</literal> is
-created and set to connection's <literal>data</literal> field
+created and set to the connection's <literal>data</literal> field.
 </listitem>
 <listitem>
-<literal>ngx_http_process_request_line()</literal> is a read event handler,
+<literal>ngx_http_process_request_line()</literal> read event handler
-which reads client request line.
+reads client request line.
 The handler is set by <literal>ngx_http_wait_request_handler()</literal>.
-Reading is done into connection's <literal>buffer</literal>.
+The data is read into connection's <literal>buffer</literal>.
 The size of the buffer is initially set by the directive
 <link doc="../http/ngx_http_core_module.xml" id="client_header_buffer_size"/>.
-The entire client header is supposed to fit the buffer.
+The entire client header is supposed to fit in the buffer.
-If the initial size is not enough, a bigger buffer is allocated, whose size is
+If the initial size is not sufficient, a bigger buffer is allocated,
-set by the <literal>large_client_header_buffers</literal> directive
+with the capacity set by the <literal>large_client_header_buffers</literal>
-</listitem>
+directive.
+</listitem>
-<listitem>
-<literal>ngx_http_process_request_headers()</literal> is a read event handler,
+<listitem>
-which is set after <literal>ngx_http_process_request_line()</literal> to read
+<literal>ngx_http_process_request_headers()</literal> read event handler,
-client request header
+is set after <literal>ngx_http_process_request_line()</literal> to read
+the client request header.
 </listitem>
 <listitem>
 <literal>ngx_http_core_run_phases()</literal> is called when the request header
 is completely read and parsed.
 This function runs request phases from
 <literal>NGX_HTTP_POST_READ_PHASE</literal> to
 <literal>NGX_HTTP_CONTENT_PHASE</literal>.
-The last phase is supposed to generate response and pass it along the filter
+The last phase is intended to generate a response and pass it along the filter
 chain.
 The response is not necessarily sent to the client at this phase.
-It may remain buffered and will be sent at the finalization stage
+It might remain buffered and be sent at the finalization stage.
 </listitem>
 <listitem>
 <literal>ngx_http_finalize_request()</literal> is usually called when the
 request has generated all the output or produced an error.
 In the latter case an appropriate error page is looked up and used as the
 response.
 If the response is not completely sent to the client by this point, an
 HTTP writer <literal>ngx_http_writer()</literal> is activated to finish
-sending outstanding data
+sending outstanding data.
 </listitem>
 <listitem>
-<literal>ngx_http_finalize_connection()</literal> is called when the response is
+<literal>ngx_http_finalize_connection()</literal> is called when the complete
-completely sent to the client and the request can be destroyed.
+response has been sent to the client and the request can be destroyed.
-If client connection keepalive feature is enabled,
+If the client connection keepalive feature is enabled,
-<literal>ngx_http_set_keepalive()</literal> is called, which destroys current
+<literal>ngx_http_set_keepalive()</literal> is called, which destroys the
-request and waits for the next request on the connection.
+current request and waits for the next request on the connection.
 Otherwise, <literal>ngx_http_close_request()</literal> destroys both the
-request and the connection
+request and the connection.
 </listitem>
 </list>
 </section>
 <section name="Request" id="http_request">
 <para>
 For each client HTTP request the <literal>ngx_http_request_t</literal> object is
-created.  Some of the fields of this object:
+created.  Some of the fields of this object are:
 </para>
 <list type="bullet">
 <listitem>
 <para>
-<literal>connection</literal> — pointer to a <literal>ngx_connection_t</literal>
+<literal>connection</literal> — Pointer to a <literal>ngx_connection_t</literal>
 client connection object.
-Several requests may reference the same connection object at the same time -
+Several requests can reference the same connection object at the same time -
 one main request and its subrequests.
-After a request is deleted, a new request may be created on the same connection.
+After a request is deleted, a new request can be created on the same connection.
 </para>
 <para>
 Note that for HTTP connections <literal>ngx_connection_t</literal>'s
 <literal>data</literal> field points back to the request.
-Such request is called active, as opposed to the other requests tied with the
+Such requests are called active, as opposed to the other requests tied to the
 connection.
-Active request is used to handle client connection events and is allowed to
+An active request is used to handle client connection events and is allowed to
 output its response to the client.
-Normally, each request becomes active at some point to be able to send its
+Normally, each request becomes active at some point so that it can send its
-output
+output.
 </para>
 </listitem>
 <listitem>
 <para>
-<literal>ctx</literal> — array of HTTP module contexts.
+<literal>ctx</literal> — Array of HTTP module contexts.
 Each module of type <literal>NGX_HTTP_MODULE</literal> can store any value
 (normally, a pointer to a structure) in the request.
 The value is stored in the <literal>ctx</literal> array at the module's
 <literal>ctx_index</literal> position.
 The following macros provide a convenient way to get and set request contexts:
 </para>
 <list type="bullet">
 <listitem>
-<literal>ngx_http_get_module_ctx(r, module)</literal> — returns
+<literal>ngx_http_get_module_ctx(r, module)</literal> — Returns
-<literal>module</literal>'s context
+the <literal>module</literal>'s context
 </listitem>
 <listitem>
-<literal>ngx_http_set_ctx(r, c, module)</literal> — sets <literal>c</literal>
+<literal>ngx_http_set_ctx(r, c, module)</literal> — Sets <literal>c</literal>
-as <literal>module</literal>'s context
+as the <literal>module</literal>'s context
 </listitem>
 </list>
 </listitem>
 <listitem>
-<literal>main_conf, srv_conf, loc_conf</literal> — arrays of current request
+<literal>main_conf</literal>, <literal>srv_conf</literal>,
+<literal>loc_conf</literal> — Arrays of current request
 configurations.
-Configurations are stored at module's <literal>ctx_index</literal> positions
+Configurations are stored at the module's <literal>ctx_index</literal>
+positions.
 </listitem>
 <listitem>
 <literal>read_event_handler</literal>, <literal>write_event_handler</literal> -
-read and write event handlers for the request.
+Read and write event handlers for the request.
-Normally, an HTTP connection has <literal>ngx_http_request_handler()</literal>
+Normally, both the read and write event handlers for an HTTP connection
-set as both read and write event handlers.
+are set to <literal>ngx_http_request_handler()</literal>.
-This function calls <literal>read_event_handler</literal> and
+This function calls the <literal>read_event_handler</literal> and
-<literal>write_event_handler</literal> handlers of the currently active request
+<literal>write_event_handler</literal> handlers for the currently
-</listitem>
+active request.
+</listitem>
-<listitem>
-<literal>cache</literal> — request cache object for caching upstream response
+<listitem>
-</listitem>
+<literal>cache</literal> — Request cache object for caching the
+upstream response.
-<listitem>
+</listitem>
-<literal>upstream</literal> — request upstream object for proxying
-</listitem>
+<listitem>
+<literal>upstream</literal> — Request upstream object for proxying.
-<listitem>
+</listitem>
-<literal>pool</literal> — request pool.
-This pool is destroyed when the request is deleted.
+<listitem>
-The request object itself is allocated in this pool.
+<literal>pool</literal> — Request pool.
-For allocations which should be available throughout the client connection's
+The request object itself is allocated in this pool, which is destroyed when
-lifetime, <literal>ngx_connection_t</literal>'s pool should be used instead
+the request is deleted.
-</listitem>
+For allocations that need to be available throughout the client connection's
+lifetime, use <literal>ngx_connection_t</literal>'s pool instead.
-<listitem>
+</listitem>
-<literal>header_in</literal> — buffer where client HTTP request header in read
-</listitem>
+<listitem>
+<literal>header_in</literal> — Buffer into which the client HTTP request
-<listitem>
+header is read.
-<literal>headers_in, headers_out</literal> — input and output HTTP headers
+</listitem>
-objects.
+<listitem>
+<literal>headers_in</literal>, <literal>headers_out</literal> — Input and
+output HTTP headers objects.
 Both objects contain the <literal>headers</literal> field of type
-<literal>ngx_list_t</literal> keeping the raw list of headers.
+<literal>ngx_list_t</literal> for keeping the raw list of headers.
 In addition to that, specific headers are available for getting and setting as
 separate fields, for example <literal>content_length_n</literal>,
-<literal>status</literal> etc
+<literal>status</literal> etc.
 </listitem>
 <listitem>
-<literal>request_body</literal> — client request body object
+<literal>request_body</literal> — Client request body object.
 </listitem>
 <listitem>
-<literal>start_sec, start_msec</literal> — time point when the request was
+<literal>start_sec</literal>, <literal>start_msec</literal> — Time point when
-created.
+the request was created, used for tracking request duration.
-Used for tracking request duration
+</listitem>
-</listitem>
+<listitem>
-<listitem>
+<literal>method</literal>, <literal>method_name</literal> — Numeric and text
-<literal>method, method_name</literal> — numeric and textual representation of
+representation of the client HTTP request method.
-client HTTP request method.
 Numeric values for methods are defined in
-<literal>src/http/ngx_http_request.h</literal> with macros
+<literal>src/http/ngx_http_request.h</literal> with the macros
-<literal>NGX_HTTP_GET, NGX_HTTP_HEAD, NGX_HTTP_POST</literal> etc
+<literal>NGX_HTTP_GET</literal>, <literal>NGX_HTTP_HEAD</literal>,
-</listitem>
+<literal>NGX_HTTP_POST</literal>, etc.
+</listitem>
-<listitem>
-<literal>http_protocol, http_version, http_major, http_minor</literal> -
+<listitem>
-client HTTP protocol version in its original textual form (“HTTP/1.0”,
+<literal>http_protocol</literal>  — Client HTTP protocol version in its
-“HTTP/1.1” etc), numeric form (<literal>NGX_HTTP_VERSION_10</literal>,
+original text form (“HTTP/1.0”, “HTTP/1.1” etc).
-<literal>NGX_HTTP_VERSION_11</literal> etc) and separate major and minor
+</listitem>
-versions
-</listitem>
+<listitem>
+<literal>http_version</literal>  — Client HTTP protocol version in
-<listitem>
+numeric form  (<literal>NGX_HTTP_VERSION_10</literal>,
-<literal>request_line, unparsed_uri</literal> — client original request line
+<literal>NGX_HTTP_VERSION_11</literal>, etc.).
-and URI
+</listitem>
-</listitem>
+<listitem>
-<listitem>
+<literal>http_major</literal>, <literal>http_minor</literal>  — Client HTTP
-<literal>uri, args, exten</literal> — current request URI, arguments and file
+protocol version in numeric form split into major and minor parts.
-extention.
+</listitem>
+<listitem>
+<literal>request_line</literal>, <literal>unparsed_uri</literal> — Request line
+and URI in the original client request.
+</listitem>
+<listitem>
+<literal>uri</literal>, <literal>args</literal>, <literal>exten</literal> —
+URI, arguments and file extension for the current request.
 The URI value here might differ from the original URI sent by the client due to
 normalization.
-Throughout request processing, these value can change while performing internal
+Throughout request processing, these values can change as internal redirects
-redirects
+are performed.
 </listitem>
 <listitem>
-<literal>main</literal> — pointer to a main request object.
+<literal>main</literal> — Pointer to a main request object.
-This object is created to process client HTTP request, as opposed to
+This object is created to process a client HTTP request, as opposed to
-subrequests, created to perform a specific sub-task within the main request
+subrequests, which are created to perform a specific subtask within the main
-</listitem>
+request.
+</listitem>
-<listitem>
-<literal>parent</literal> — pointer to a parent request of a subrequest
+<listitem>
-</listitem>
+<literal>parent</literal> — Pointer to the parent request of a subrequest.
+</listitem>
-<listitem>
-<literal>postponed</literal> — list of output buffers and subrequests in the
+<listitem>
-order they are sent and created.
+<literal>postponed</literal> — List of output buffers and subrequests, in the
-The list is used by the postpone filter to provide consistent request output,
+order in which they are sent and created.
-when parts of it are created by subrequests
+The list is used by the postpone filter to provide consistent request output
-</listitem>
+when parts of it are created by subrequests.
+</listitem>
-<listitem>
-<literal>post_subrequest</literal> — pointer to a handler with context to be
+<listitem>
-called when a subrequest gets finalized.
+<literal>post_subrequest</literal> — Pointer to a handler with the context
-Unused for main requests
+to be called when a subrequest gets finalized.
-</listitem>
+Unused for main requests.
+</listitem>
-<listitem>
+<listitem>
-<para>
-<literal>posted_requests</literal> — list of requests to be started or
+<para>
-resumed.
+<literal>posted_requests</literal> — List of requests to be started or
-Starting or resuming is done by calling the request's
+resumed, which is done by calling the request's
 <literal>write_event_handler</literal>.
 Normally, this handler holds the request main function, which at first runs
 request phases and then produces the output.
 </para>
 <para>
 A request is usually posted by the
 <literal>ngx_http_post_request(r, NULL)</literal> call.
 It is always posted to the main request <literal>posted_requests</literal> list.
 The function <literal>ngx_http_run_posted_requests(c)</literal> runs all
-requests, posted in the main request of the passed connection's active request.
+requests that are posted in the main request of the passed
-This function should be called in all event handlers, which can lead to new
+connection's active request.
-posted requests.
+All event handlers call <literal>ngx_http_run_posted_requests</literal>,
-Normally, it's called always after invoking a request's read or write handler
+which can lead to new posted requests.
-</para>
+Normally, it is called after invoking a request's read or write handler.
+</para>
-</listitem>
+</listitem>
-<listitem>
-<literal>phase_handler</literal> — index of current request phase
+<listitem>
-</listitem>
+<literal>phase_handler</literal> — Index of current request phase.
+</listitem>
-<listitem>
-<literal>ncaptures, captures, captures_data</literal> — regex captures produced
+<listitem>
+<literal>ncaptures</literal>, <literal>captures</literal>,
+<literal>captures_data</literal> — 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
+A regex match can occur at a number of places during request processing:
-happen: map lookup, server lookup by SNI or HTTP Host, rewrite, proxy_redirect
+map lookup, server lookup by SNI or HTTP Host, rewrite, proxy_redirect, etc.
-etc.
 Captures produced by a lookup are stored in the above mentioned fields.
 The field <literal>ncaptures</literal> holds the number of captures,
-<literal>captures</literal> holds captures boundaries,
+<literal>captures</literal> holds captures boundaries and
-<literal>captures_data</literal> holds a string, against which the regex was
+<literal>captures_data</literal> holds the string against which the regex was
-matched and which should be used to extract captures.
+matched and which is used to extract captures.
-After each new regex match request captures are reset to hold new values
+After each new regex match, request captures are reset to hold new values.
 </listitem>
 <listitem>
-<literal>count</literal> — request reference counter.
+<literal>count</literal> — Request reference counter.
 The field only makes sense for the main request.
 Increasing the counter is done by simple <literal>r->main->count++</literal>.
-To decrease the counter <literal>ngx_http_finalize_request(r, rc)</literal>
+To decrease the counter, call
-should be called.
+<literal>ngx_http_finalize_request(r, rc)</literal>.
-Creation of a subrequest or running request body read process increase the
+Creating of a subrequest and running the request body read process both
-counter
+increment the counter.
 </listitem>
 <listitem>
-<literal>subrequests</literal> — current subrequest nesting level.
+<literal>subrequests</literal> — Current subrequest nesting level.
-Each subrequest gets the nesting level of its parent decreased by one.
+Each subrequest inherits its parent's nesting level, decreased by one.
-Once the value reaches zero an error is generated.
+An error is generated if the value reaches zero.
 The value for the main request is defined by the
-<literal>NGX_HTTP_MAX_SUBREQUESTS</literal> constant
+<literal>NGX_HTTP_MAX_SUBREQUESTS</literal> constant.
 </listitem>
 <listitem>
-<literal>uri_changes</literal> — number of URI changes left for the request.
+<literal>uri_changes</literal> — Number of URI changes remaining for
+the request.
 The total number of times a request can change its URI is limited by the
 <literal>NGX_HTTP_MAX_URI_CHANGES</literal> constant.
-With each change the value is decreased until it reaches zero.
+With each change the value is decremented until it reaches zero, at which time
-In the latter case an error is generated.
+an error is generated.
-The actions considered as URI changes are rewrites and internal redirects to
+Rewrites and internal redirects to normal or named locations are considered URI
-normal or named locations
+changes.
 </listitem>
 <listitem>
-<literal>blocked</literal> — counter of blocks held on the request.
+<literal>blocked</literal> — Counter of blocks held on the request.
-While this value is non-zero, request cannot be terminated.
+While this value is non-zero, the request cannot be terminated.
 Currently, this value is increased by pending AIO operations (POSIX AIO and
-thread operations) and active cache lock
+thread operations) and active cache lock.
 </listitem>
 <listitem>
-<literal>buffered</literal> — bitmask showing which modules have buffered the
+<literal>buffered</literal> — 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
+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
+because of a partial string match, copy filter can buffer data because of the
-of free output_buffers etc.
+lack of free output buffers etc.
-As long as this value is non-zero, request is not finalized, expecting the flush
+As long as this value is non-zero, the request is not finalized
-</listitem>
+pending the flush.
+</listitem>
-<listitem>
-<literal>header_only</literal> — flag showing that output does not require body.
+<listitem>
-For example, this flag is used by HTTP HEAD requests
+<literal>header_only</literal> — Flag indicating that the output does not
-</listitem>
+require a body.
+For example, this flag is used by HTTP HEAD requests.
-<listitem>
+</listitem>
-<para>
-<literal>keepalive</literal> — flag showing if client connection keepalive is
+<listitem>
-supported.
+<para>
-The value is inferred from HTTP version and <header>Connection</header> header
+<literal>keepalive</literal> — Flag indicating whether client connection
-value
+keepalive is supported.
-</para>
+The value is inferred from the HTTP version and the value of the
-</listitem>
+<header>Connection</header> header.
+</para>
-<listitem>
+</listitem>
-<literal>header_sent</literal> — flag showing that output header has already
-been sent by the request
+<listitem>
-</listitem>
+<literal>header_sent</literal> — Flag indicating that the output header
+has already been sent by the request.
-<listitem>
+</listitem>
-<literal>internal</literal> — flag showing that current request is internal.
-To enter the internal state, a request should pass through an internal
+<listitem>
+<literal>internal</literal> — Flag indicating that the current request
+is internal.
+To enter the internal state, a request must pass through an internal
 redirect or be a subrequest.
-Internal requests are allowed to enter internal locations
+Internal requests are allowed to enter internal locations.
 </listitem>
 <listitem>
-<literal>allow_ranges</literal> — flag showing that partial response can be
+<literal>allow_ranges</literal> — Flag indicating that a partial response
-sent to client, if requested by the HTTP Range header
+can be sent to the client, as requested by the HTTP Range header.
 </listitem>
 <listitem>
-<literal>subrequest_ranges</literal> — flag showing that a partial response is
+<literal>subrequest_ranges</literal> — Flag indicating that a partial response
-allowed to be sent while processing a subrequest
+can be sent while a subrequest is being processed.
 </listitem>
 <listitem>
-<literal>single_range</literal> — flag showing that only a single continuous
+<literal>single_range</literal> — Flag indicating 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
+proxied server, and the entire response is not available in one buffer.
 </listitem>
 <listitem>
-<literal>main_filter_need_in_memory, filter_need_in_memory</literal> — flags
+<literal>main_filter_need_in_memory</literal>,
-showing that the output should be produced in memory buffers but not in files.
+<literal>filter_need_in_memory</literal> — Flags
+requesting that the output produced in memory buffers rather than files.
 This is a signal to the copy filter to read data from file buffers even if
 sendfile is enabled.
-The difference between these two flags is the location of filter modules which
+The difference between the two flags is the location of the filter modules that
 set them.
-Filters called before the postpone filter in filter chain, set
+Filters called before the postpone filter in the filter chain set
-<literal>filter_need_in_memory</literal> requesting that only the current
+<literal>filter_need_in_memory</literal>, requesting that only the current
-request output should come in memory buffers.
+request output come in memory buffers.
-Filters called later in filter chain set
+Filters called later in the filter chain set
-<literal>main_filter_need_in_memory</literal> requiring that both the main
+<literal>main_filter_need_in_memory</literal>, requesting that
-request and all the subrequest read files in memory while sending output
+both the main request and all subrequests read files in memory
-</listitem>
+while sending output.
+</listitem>
-<listitem>
-<literal>filter_need_temporary</literal> — flag showing that the request output
+<listitem>
-should be produced in temporary buffers, but not in readonly memory buffers or
+<literal>filter_need_temporary</literal> — Flag requesting that the request
+output 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
+This is used by filters which may change output directly in the buffers where
-it's sent </listitem>
+it's sent.</listitem>
 </list>
 </section>
 <section name="Configuration" id="http_conf">
 <para>
-Each HTTP module may have three types of configuration:
+Each HTTP module can have three types of configuration:
 </para>
 <list type="bullet">
 <listitem>
-Main configuration.
+Main configuration — Applies to the entire <literal>http</literal> block.
-This configuration applies to the entire nginx http{} block.  This is global
+Functions as global settings for a module.
-configuration.
+</listitem>
-It stores global settings for a module
-</listitem>
+<listitem>
+Server configuration — Applies to a single <literal>server</literal> block.
-<listitem>
+Functions as server-specific settings for a module.
-Server configuration.
+</listitem>
-This configuration applies to a single nginx server{}.
-It stores server-specific settings for a module
+<listitem>
-</listitem>
+Location configuration — Applies to a single <literal>location</literal>,
+<literal>if</literal> or <literal>limit_except</literal> block.
-<listitem>
+Functions as location-specific settings for a module.
-Location configuration.
+</listitem>
-This configuration applies to a single location{}, if{} or limit_except() block.
-This configuration stores settings specific to a location
+</list>
-</listitem>
+<para>
-</list>
+Configuration structures are created at the nginx configuration stage by
+calling functions, which allocate the structures, initialize them
-<para>
+and merge them.
-Configuration structures are created at nginx configuration stage by calling
+The following example shows how to create a simple location
-functions, which allocate these structures, initialize them and merge.
+configuration for a module.
-The following example shows how to create a simple module location
+The configuration has one setting, <literal>foo</literal>, of type
-configuration.
+unsigned integer.
-The configuration has one setting <literal>foo</literal> of unsiged integer
-type.
 </para>
 <programlisting>
 typedef struct {
 ngx_uint_t  foo;
 ngx_conf_merge_uint_value(conf->foo, prev->foo, 1);
 }
 </programlisting>
 <para>
-As seen in the example, <literal>ngx_http_foo_create_loc_conf()</literal>
+As seen in the example, the <literal>ngx_http_foo_create_loc_conf()</literal>
-function creates a new configuration structure and
+function creates a new configuration structure, and
 <literal>ngx_http_foo_merge_loc_conf()</literal> merges a configuration with
-another configuration from a higher level.
+configuration from a higher level.
-In fact, server and location configuration do not only exist at server and
+In fact, server and location configuration do not exist only at the server and
-location levels, but also created for all the levels above.
+location levels, but are also created for all levels above them.
-Specifically, a server configuration is created at the main level as well and
+Specifically, a server configuration is also created at the main level and
-location configurations are created for main, server and location levels.
+location configurations are created at the main, server, and location levels.
-These configurations make it possible to specify server and location-specific
+These configurations make it possible to specify server- and location-specific
-settings at any level of nginx configuration file.
+settings at any level of an nginx configuration file.
 Eventually configurations are merged down.
-To indicate a missing setting and ignore it while merging, nginx provides a
+A number of macros like <literal>NGX_CONF_UNSET</literal> and
-number of macros like <literal>NGX_CONF_UNSET</literal> and
+<literal>NGX_CONF_UNSET_UINT</literal> are provided
-<literal>NGX_CONF_UNSET_UINT</literal>.
+for indicating a missing setting and ignoring it while merging.
 Standard nginx merge macros like <literal>ngx_conf_merge_value()</literal> and
 <literal>ngx_conf_merge_uint_value()</literal> provide a convenient way to
-merge a setting and set the default value if none of configurations provided an
+merge a setting and set the default value if none of the configurations
-explicit value.
+provided an explicit value.
-For complete list of macros for different types see
+For complete list of macros for different types, see
 <literal>src/core/ngx_conf_file.h</literal>.
 </para>
 <para>
-To access configuration of any HTTP module at configuration time, the following
+The following macros are available.
-macros are available.
+for accessing configuration for HTTP modules at configuration time.
-They receive <literal>ngx_conf_t</literal> reference as the first argument.
+They all take <literal>ngx_conf_t</literal> reference as the first argument.
 </para>
 <list type="bullet">
 <listitem>
 <para>
 The following example gets a pointer to a location configuration of
 standard nginx core module
 <link doc="../http/ngx_http_core_module.xml">ngx_http_core_module</link>
-and changes
+and replaces the location content handler kept
-location content handler kept in the <literal>handler</literal> field of the
+in the <literal>handler</literal> field of the structure.
-structure.
 </para>
 <programlisting>
 static ngx_int_t ngx_http_foo_handler(ngx_http_request_t *r);
 return NGX_CONF_OK;
 }
 </programlisting>
 <para>
-In runtime the following macros are available to get configurations of HTTP
+The following macros are available for accessing configuration for HTTP
-modules.
+modules at runtime.
 </para>
 <list type="bullet">
 <listitem>
 </list>
 <para>
 These macros receive a reference to an HTTP request
 <literal>ngx_http_request_t</literal>.
-Main configuration of a request never changes.
+The main configuration of a request never changes.
-Server configuration may change from a default one after choosing a virtual
+Server configuration can change from the default after
-server for a request.
+the virtual server for the request is chosen.
-Request location configuration may change multiple times as a result of a
+Location configuration selected for processing a request can change multiple
-rewrite or internal redirect.
+times as a result of a rewrite operation or internal redirect.
-The following example shows how to access HTTP configuration in runtime.
+The following example shows how to access a module's HTTP configuration at
+runtime.
 </para>
 <programlisting>
 static ngx_int_t
 ngx_http_foo_handler(ngx_http_request_t *r)
 <section name="Phases" id="http_phases">
 <para>
-Each HTTP request passes through a list of HTTP phases.
+Each HTTP request passes through a sequence of phases.
-Each phase is specialized in a particular type of processing.
+In each phase a distinct type of processing is performed on the request.
-Most phases allow installing handlers.
+Module-specific handlers can be registered in most phases,
-The phase handlers are called successively once the request reaches the phase.
+and many standard nginx modules register their phase handlers as a way
-Many standard nginx modules install their phase handlers as a way to get called
+to get called at a specific stage of request processing.
-at a specific request processing stage.
+Phases are processed successively and the phase handlers are called
+once the request reaches the phase.
 Following is the list of nginx HTTP phases.
 </para>
 <list type="bullet">
 <listitem>
-<literal>NGX_HTTP_POST_READ_PHASE</literal> is the earliest phase.
+<literal>NGX_HTTP_POST_READ_PHASE</literal> — First phase.
 The <link doc="../http/ngx_http_realip_module.xml">ngx_http_realip_module</link>
-installs its handler at this phase.
+registers its handler at this phase to enable
-This allows to substitute client address before any other module is invoked
+substitution of client addresses before any other module is invoked.
 </listitem>
 <listitem>
-<literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal> is used to run rewrite script,
+<literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal> — Phase where
-defined at the server level, that is out of any location block.
+rewrite directives defined in a <literal>server</literal> block
+(but outside a <literal>location</literal> block) are processed.
 The
 <link doc="../http/ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>
-installs its handler at this phase
+installs its handler at this phase.
 </listitem>
 <listitem>
-<literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> — a special phase used to choose a
+<literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> — Special phase
-location based on request URI.
+where a location is chosen based on the request URI.
-This phase does not allow installing any handlers.
+Before this phase, the default location for the relevant virtual server
-It only performs the default action of choosing a location.
+is assigned to the request, and any module requesting a location configuration
-Before this phase, the server default location is assigned to the request.
+receives the configuration for the default server location.
-Any module requesting a location configuration, will receive the default server
+This phase a assigns a new location to the request.
-location configuration.
+No additional handlers can be registered at this phase.
-After this phase a new location is assigned to the request
+</listitem>
-</listitem>
+<listitem>
-<listitem>
+<literal>NGX_HTTP_REWRITE_PHASE</literal> — Same as
-<literal>NGX_HTTP_REWRITE_PHASE</literal> — same as
+<literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal>, but for
-<literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal>, but for a new location,
+rewrite rules defined in the location, chosen in the previous phase.
-chosen at the previous phase
+</listitem>
-</listitem>
+<listitem>
-<listitem>
+<literal>NGX_HTTP_POST_REWRITE_PHASE</literal> — Special phase
-<literal>NGX_HTTP_POST_REWRITE_PHASE</literal> — a special phase, used to
+where the request is redirected to a new location if its URI changed
-redirect the request to a new location, if the URI was changed during rewrite.
+during a rewrite.
-The redirect is done by going back to
+This is implemented by the request going through
-<literal>NGX_HTTP_FIND_CONFIG_PHASE</literal>.
+the <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> again.
-No handlers are allowed at this phase
+No additional handlers can be registered at this phase.
 </listitem>
 <listitem>
-<literal>NGX_HTTP_PREACCESS_PHASE</literal> — a common phase for different
+<literal>NGX_HTTP_PREACCESS_PHASE</literal> — A common phase for different
-types of handlers, not associated with access check.
+types of handlers, not associated with access control.
-Standard nginx modules
+The standard nginx modules
 <link doc="../http/ngx_http_limit_conn_module.xml">ngx_http_limit_conn_module
 </link> and
 <link doc="../http/ngx_http_limit_req_module.xml">
-ngx_http_limit_req_module</link> register their handlers at this phase
+ngx_http_limit_req_module</link> register their handlers at this phase.
 </listitem>
 <listitem>
-<literal>NGX_HTTP_ACCESS_PHASE</literal> — used to check access permissions
+<literal>NGX_HTTP_ACCESS_PHASE</literal> — Phase where it is verified
-for the request.
+that the client is authorized to make the request.
 Standard nginx modules such as
 <link doc="../http/ngx_http_access_module.xml">ngx_http_access_module</link> and
 <link doc="../http/ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module
 </link> register their handlers at this phase.
-If configured so by the
+By default the client must pass the authorization check of all handlers
-<link doc="../http/ngx_http_core_module.xml" id="satisfy"/> directive, only one
+registered at this phase for the request to continue to the next phase.
-of access phase handlers may allow access to the request in order to continue
+The <link doc="../http/ngx_http_core_module.xml" id="satisfy"/> directive,
-processing
+can be used to permit processing to continue if any of the phase handlers
-</listitem>
+authorizes the client.
+</listitem>
-<listitem>
-<literal>NGX_HTTP_POST_ACCESS_PHASE</literal> — a special phase for the
+<listitem>
+<literal>NGX_HTTP_POST_ACCESS_PHASE</literal> — Special phase where the
 <link doc="../http/ngx_http_core_module.xml" id="satisfy">satisfy any</link>
-case.
+directive is processed.
-If some access phase handlers denied the access and none of them allowed, the
+If some access phase handlers denied access and none explictly allowed it, the
 request is finalized.
-No handlers are supported at this phase
+No additional handlers can be registered at this phase.
 </listitem>
 <listitem>
-<literal>NGX_HTTP_TRY_FILES_PHASE</literal> — a special phase, for the
+<literal>NGX_HTTP_TRY_FILES_PHASE</literal> — Special phase where
-<link doc="../http/ngx_http_core_module.xml" id="try_files"/> feature.
+the <link doc="../http/ngx_http_core_module.xml" id="try_files"/> directive
-No handlers are allowed at this phase
+is processed.
-</listitem>
+No additional handlers can be registered at this phase.
+</listitem>
-<listitem>
-<literal>NGX_HTTP_CONTENT_PHASE</literal> — a phase, at which the response
+<listitem>
-is supposed to be generated.
+<literal>NGX_HTTP_CONTENT_PHASE</literal> — Phase where the response
-Multiple nginx standard modules register their handers at this phase, for
+is normally generated.
-example
+Multiple nginx standard modules register their handlers at this phase,
+including
 <link doc="../http/ngx_http_index_module.xml">ngx_http_index_module</link> or
 <literal>ngx_http_static_module</literal>.
-All these handlers are called sequentially until one of them finally produces
+They are called sequentially until one of them produces
 the output.
 It's also possible to set content handlers on a per-location basis.
 If the
 <link doc="../http/ngx_http_core_module.xml">ngx_http_core_module</link>'s
-location configuration has <literal>handler</literal> set, this handler is
+location configuration has <literal>handler</literal> set, it is
-called as the content handler and content phase handlers are ignored
+called as the content handler and the handlers installed at this phase
-</listitem>
+are ignored.
+</listitem>
-<listitem>
-<literal>NGX_HTTP_LOG_PHASE</literal> is used to perform request logging.
+<listitem>
+<literal>NGX_HTTP_LOG_PHASE</literal> — Phase where request logging
+is performed.
 Currently, only the
 <link doc="../http/ngx_http_log_module.xml">ngx_http_log_module</link>
 registers its handler
 at this stage for access logging.
 Log phase handlers are called at the very end of request processing, right
-before freeing the request
+before freeing the request.
 </listitem>
 </list>
 <para>
 </para>
 <list type="bullet">
 <listitem>
-<literal>NGX_OK</literal> — proceed to the next phase
+<literal>NGX_OK</literal> — Proceed to the next phase.
 </listitem>
 <listitem>
-<literal>NGX_DECLINED</literal> — proceed to the next handler of the current
+<literal>NGX_DECLINED</literal> — Proceed to the next handler of the current
 phase.
-If current handler is the last in current phase, move to the next phase
+If the current handler is the last in the current phase,
-</listitem>
+move to the next phase.
+</listitem>
-<listitem>
-<literal>NGX_AGAIN, NGX_DONE</literal> — suspend phase handling until some
+<listitem>
-future event.
+<literal>NGX_AGAIN</literal>, <literal>NGX_DONE</literal> — Suspend
-This can be for example asynchronous I/O operation or just a delay.
+phase handling until some future event which can be
-It is supposed, that phase handling will be resumed later by calling
+an asynchronous I/O operation or just a delay, for example.
-<literal>ngx_http_core_run_phases()</literal>
+It is assumed, that phase handling will be resumed later by calling
+<literal>ngx_http_core_run_phases()</literal>.
 </listitem>
 <listitem>
 Any other value returned by the phase handler is treated as a request
-finalization code, in particular, HTTP response code.
+finalization code, in particular, an HTTP response code.
-The request is finalized with the code provided
+The request is finalized with the code provided.
 </listitem>
 </list>
 <para>
-Some phases treat return codes in a slightly different way.
+For some phases, return codes are treated in a slightly different way.
-At content phase, any return code other that <literal>NGX_DECLINED</literal>
+At the content phase, any return code other that
-is considered a finalization code.
+<literal>NGX_DECLINED</literal> is considered a finalization code.
-As for the location content handlers, any return from them is considered a
+Any return code from the location content handlers is considered a
 finalization code.
-At access phase, in
+At the access phase, in
 <link doc="../http/ngx_http_core_module.xml" id="satisfy">satisfy any</link>
-mode, returning a code other
+mode,
-than <literal>NGX_OK, NGX_DECLINED, NGX_AGAIN, NGX_DONE</literal> is considered
+any return code other than <literal>NGX_OK</literal>,
-a denial.
+<literal>NGX_DECLINED</literal>, <literal>NGX_AGAIN</literal>,
-If none of future access handlers allow access or deny with a new
+<literal>NGX_DONE</literal> is considered a denial.
+If no subsequent access handlers allow or deny access with a different
 code, the denial code will become the finalization code.
 </para>
 </section>
 <section name="Variables" id="http_variables">
 <section name="Accessing existing variables" id="http_existing_variables">
 <para>
-Variables may be referenced using index (this is the most common method)
+Variables can be referenced by index (this is the most common method)
-or names (see below in the section about creating variables).
+or name (see <link id="http_creating_variables">below</link>).
-Index is created at configuration stage, when a variable is added
+The index is created at configuration stage, when a variable is added
-to configuration.
+to the configuration.
-The variable index can be obtained using
+To obtain the variable index, use
 <literal>ngx_http_get_variable_index()</literal>:
 <programlisting>
 ngx_str_t  name;  /* ngx_string("foo") */
 ngx_int_t  index;
 index = ngx_http_get_variable_index(cf, &amp;name);
 </programlisting>
-Here, the <literal>cf</literal> is a pointer to nginx configuration and the
+Here, <literal>cf</literal> is a pointer to nginx configuration and
-<literal>name</literal> points to a string with the variable name.
+<literal>name</literal> points to a string containing the variable name.
-The function returns <literal>NGX_ERROR</literal> on error or valid index
+The function returns <literal>NGX_ERROR</literal> on error or a valid index
-otherwise, which is typically stored somewhere in a module configuration for
+otherwise, which is typically stored somewhere in the module's
-future use.
+configuration for future use.
 </para>
 <para>
-All HTTP variables are evaluated in the context of HTTP request and results
+All HTTP variables are evaluated in the context of a given HTTP request,
-are specific to and cached in HTTP request.
+and results are specific to and cached in that HTTP request.
-All functions that evaluate variables return
+All functions that evaluate variables return the
 <literal>ngx_http_variable_value_t</literal> type, representing
 the variable value:
 <programlisting>
 typedef ngx_variable_value_t  ngx_http_variable_value_t;
 </programlisting>
 where:
 <list type="bullet">
 <listitem>
-<literal>len</literal> — length of a value
+<literal>len</literal> — The length of the value
 </listitem>
 <listitem>
-<literal>data</literal> — value itself
+<literal>data</literal> — The value itself
 </listitem>
 <listitem>
-<literal>valid</literal> — value is valid
+<literal>valid</literal> — The value is valid
 </listitem>
 <listitem>
-<literal>not_found</literal> — variable was not found and thus
+<literal>not_found</literal> — The variable was not found and thus
 the <literal>data</literal> and <literal>len</literal> fields are irrelevant;
-this may happen, for example, with such variables as <var>$arg_foo</var>
+this can happen, for example, with variables like <var>$arg_foo</var>
 when a corresponding argument was not passed in a request
 </listitem>
 <listitem>
-<literal>no_cacheable</literal> — do not cache result
+<literal>no_cacheable</literal> — Do not cache result
 </listitem>
 <listitem>
-<literal>escape</literal> — used internally by the logging module to mark
+<literal>escape</literal> — Used internally by the logging module to mark
-values that require escaping on output
+values that require escaping on output.
 </listitem>
 </list>
 </para>
 <para>
 The <literal>ngx_http_get_flushed_variable()</literal>
 and <literal>ngx_http_get_indexed_variable()</literal> functions
-are used to obtain the variable value.
+are used to obtain the value of a variable.
-They have the same interface - accepting a HTTP request <literal>r</literal>
+They have the same interface - accepting an HTTP request <literal>r</literal>
-as a context for evaluating the variable and an <literal>index</literal>,
+as a context for evaluating the variable and an <literal>index</literal>
-identifying it.
+that identifies it.
-Example of typical usage:
+An example of typical usage:
 <programlisting>
 ngx_http_variable_value_t  *v;
 v = ngx_http_get_flushed_variable(r, index);
 }
 /* some meaningful value is found */
 </programlisting>
 The difference between functions is that the
-<literal>ngx_http_get_indexed_variable()</literal> returns cached value
+<literal>ngx_http_get_indexed_variable()</literal> returns a cached value
-and <literal>ngx_http_get_flushed_variable()</literal> flushes cache for
+and <literal>ngx_http_get_flushed_variable()</literal> flushes the cache for
 non-cacheable variables.
 </para>
 <para>
-There are cases when it is required to deal with variables which names are
+Some modules, such as SSI and Perl, need to deal with variables for which the
-not known at configuration time and thus they cannot be accessed using indexes,
+name is not known at configuration time.
-for example in modules like SSI or Perl.
+An index therefore cannot be used to access them, but the
-The <literal>ngx_http_get_variable(r, name, key)</literal> function may be
+<literal>ngx_http_get_variable(r, name, key)</literal> function
-used in such cases.
+is available.
-It searches for the <literal>variable</literal> with a given
+It searches for a variable with a given
-<literal>name</literal> and its hash <literal>key</literal>.
+<literal>name</literal> and its hash <literal>key</literal> derived
+from the name.
 </para>
 </section>
 <section name="Creating variables" id="http_creating_variables">
 <para>
-To create a variable <literal>ngx_http_add_variable()</literal> function
+To create a variable, use the <literal>ngx_http_add_variable()</literal>
-is used.
+function.
-It takes configuration (where variable is registered), variable name and
+It takes as arguments a configuration (where the variable is registered),
-flags that control its behaviour:
+the variable name and flags that control the function's behaviour:
 <list type="bullet">
-<listitem><literal>NGX_HTTP_VAR_CHANGEABLE</literal> — allows redefining
+<listitem><literal>NGX_HTTP_VAR_CHANGEABLE</literal> — Enables redefinition of
-the variable; If another module will define a variable with such name,
+the variable: there is no conflict if another module defines a variable with
-no conflict will happen.
+the same name.
-For example, this allows user to override variables using the
+This allows the
-<link doc="../http/ngx_http_rewrite_module.xml" id="set"/> directive.
+<link doc="../http/ngx_http_rewrite_module.xml" id="set"/> directive
-</listitem>
+to override variables.
+</listitem>
-<listitem><literal>NGX_HTTP_VAR_NOCACHEABLE</literal> — disables caching,
-is useful for such variables as <literal>$time_local</literal>
+<listitem><literal>NGX_HTTP_VAR_NOCACHEABLE</literal> — Disables caching,
-</listitem>
+which is useful for variables such as <literal>$time_local</literal>.
+</listitem>
-<listitem><literal>NGX_HTTP_VAR_NOHASH</literal> — indicates that
+<listitem><literal>NGX_HTTP_VAR_NOHASH</literal> — 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
+This is a small optimization for use when it is known that the
 variable is not needed in modules like SSI or Perl.
 </listitem>
-<listitem><literal>NGX_HTTP_VAR_PREFIX</literal> — the name of this
+<listitem><literal>NGX_HTTP_VAR_PREFIX</literal> — The name of the
 variable is a prefix.
-A handler must implement additional logic to obtain value of specific
+In this case, a handler must implement additional logic to obtain the value
-variable.
+of a specific variable.
 For example, all “<literal>arg_</literal>” variables are processed by the
-same handler which performs lookup in request arguments and returns value
+same handler, which performs lookup in request arguments and returns the value
-of specific argument.
+of a specific argument.
 </listitem>
 </list>
 The function returns NULL in case of error or a pointer to
-<literal>ngx_http_variable_t</literal>:
+<literal>ngx_http_variable_t</literal> otherwise:
 <programlisting>
 struct ngx_http_variable_s {
 ngx_str_t                     name;
 ngx_http_set_variable_pt      set_handler;
 ngx_http_get_variable_pt      get_handler;
 };
 </programlisting>
 The <literal>get</literal> and <literal>set</literal> handlers
 are called to obtain or set the variable value,
-<literal>data</literal> will be passed to variable handlers,
+<literal>data</literal> is passed to variable handlers, and
-<literal>index</literal> will hold assigned variable index, used to reference
+<literal>index</literal> holds assigned variable index used to reference
 the variable.
 </para>
 <para>
-Usually, a null-terminated static array of such structures is created
+Usually, a null-terminated static array of
+<literal>ngx_http_variable_t</literal> structures is created
 by a module and processed at the preconfiguration stage to add variables
-into configuration:
+into the configuration, for example:
 <programlisting>
 static ngx_http_variable_t  ngx_http_foo_vars[] = {
 { ngx_string("foo_v1"), NULL, ngx_http_foo_v1_variable, NULL, 0, 0 },
 }
 return NGX_OK;
 }
 </programlisting>
-This function is used to initialize the <literal>preconfiguration</literal>
+This function in the example is used to initialize
-field of the HTTP module context and is called before parsing HTTP configuration,
+the <literal>preconfiguration</literal>
-so it could refer to these variables.
+field of the HTTP module context and is called before the parsing of HTTP
-</para>
+configuration, so that the parser can refer to these variables.
+</para>
-<para>
-The <literal>get</literal> handler is responsible for evaluating the variable
+<para>
-in a context of specific request, for example:
+The <literal>get</literal> handler is responsible for evaluating a variable
+in the context of a specific request, for example:
 <programlisting>
 static ngx_int_t
 ngx_http_variable_connection(ngx_http_request_t *r,
 ngx_http_variable_value_t *v, uintptr_t data)
 {
 return NGX_OK;
 }
 </programlisting>
 It returns <literal>NGX_ERROR</literal> in case of internal error
 (for example, failed memory allocation) or <literal>NGX_OK</literal> otherwise.
-The status of variable evaluation may be understood by inspecting flags
+To learn the status of variable evaluation, inspect the flags
-of the <literal>ngx_http_variable_value_t</literal> (see description above).
+in <literal>ngx_http_variable_value_t</literal> (see the description
+<link id="http_existing_variables">above</link>).
 </para>
 <para>
 The <literal>set</literal> handler allows setting the property
-referred by the variable.
+referenced by the variable.
-For example, the <literal>$limit_rate</literal> variable set handler
+For example, the set handler of the <literal>$limit_rate</literal> variable
 modifies the request's <literal>limit_rate</literal> field:
 <programlisting>
 ...
 { ngx_string("limit_rate"), ngx_http_variable_request_set_size,
 ngx_http_variable_request_get_size,
 <section name="Complex values" id="http_complex_values">
 <para>
 A complex value, despite its name, provides an easy way to evaluate
-expressions that may contain text, variables, and their combination.
+expressions which can contain text, variables, and their combination.
 </para>
 <para>
 The complex value description in
 <literal>ngx_http_compile_complex_value</literal> is compiled at the
 configuration stage into <literal>ngx_http_complex_value_t</literal>
-which is used at runtime to obtain evaluated expression results.
+which is used at runtime to obtain results of expression evaluation.
 <programlisting>
 ngx_str_t                         *value;
 ngx_http_complex_value_t           cv;
 ngx_http_compile_complex_value_t   ccv;
 initialize the complex value <literal>cv</literal>:
 <list type="bullet">
 <listitem>
-<literal>cf</literal> — configuration pointer
+<literal>cf</literal> — Configuration pointer
 </listitem>
 <listitem>
-<literal>value</literal> — string for parsing (input)
+<literal>value</literal> — String to be parsed (input)
 </listitem>
 <listitem>
-<literal>complex_value</literal> — compiled value (output)
+<literal>complex_value</literal> — Compiled value (output)
 </listitem>
 <listitem>
-<literal>zero</literal> — flag that enables zero-terminating value
+<literal>zero</literal> — Flag that enables zero-terminating value
 </listitem>
 <listitem>
-<literal>conf_prefix</literal> — prefixes result with configuration prefix
+<literal>conf_prefix</literal> — Prefixes the result with the
-(the directory where nginx is currently looking for configuration)
+configuration prefix (the directory where nginx is currently looking for
-</listitem>
+configuration)
+</listitem>
-<listitem>
-<literal>root_prefix</literal> — prefixes result with root prefix
+<listitem>
-(this is the normal nginx installation prefix)
+<literal>root_prefix</literal> — Prefixes the result with the root prefix
-</listitem>
+(the normal nginx installation prefix)
+</listitem>
-</list>
-The <literal>zero</literal> flag is usable when results are to be passed to
+</list>
+The <literal>zero</literal> flag is useful when results are to be passed to
 libraries that require zero-terminated strings, and prefixes are handy when
 dealing with filenames.
 </para>
 <para>
-Upon successful compilation, <literal>cv.lengths</literal> may
+Upon successful compilation, <literal>cv.lengths</literal>
-be inspected to get information about the presence of variables
+contains information about the presence of variables
 in the expression.
 The NULL value means that the expression contained static text only,
-and there is no need in storing it as a complex value,
+and so can be stored in a simple string rather than as a complex value.
-so a simple string can be used.
 </para>
 <para>
 The <literal>ngx_http_set_complex_value_slot()</literal> is a convenient
-function used to initialize complex value completely right in the directive
+function used to initialize a complex value completely in the directive
-declaration.
+declaration itself.
 </para>
 <para>
-At runtime, a complex value may be calculated using the
+At runtime, a complex value can be calculated using the
 <literal>ngx_http_complex_value()</literal> function:
 <programlisting>
 ngx_str_t  res;
 if (ngx_http_complex_value(r, &amp;cv, &amp;res) != NGX_OK) {
 return NGX_ERROR;
 }
 </programlisting>
 Given the request <literal>r</literal> and previously compiled
-value <literal>cv</literal> the function will evaluate
+value <literal>cv</literal>, the function evaluates the
-expression and put result into <literal>res</literal>.
+expression and writes the result to <literal>res</literal>.
 </para>
 </section>
 <literal>loc_conf</literal> field of the <literal>ngx_http_request_t</literal>
 structure.
 This means that at any point the location configuration of any module can be
 retrieved from the request by calling
 <literal>ngx_http_get_module_loc_conf(r, module)</literal>.
-Request location may be changed several times throughout its lifetime.
+Request location can change several times during the request's lifetime.
 Initially, a default server location of the default server is assigned to a
 request.
-Once a request switches to a different server (chosen by the HTTP
+If the request switches to a different server (chosen by the HTTP
 <header>Host</header> header or SSL SNI extension), the request switches to the
 default location of that server as well.
 The next change of the location takes place at the
 <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> request phase.
 At this phase a location is chosen by request URI among all non-named locations
 configured for the server.
 The
 <link doc="../http/ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>
-may change the request URI at the
+can change the request URI at the
 <literal>NGX_HTTP_REWRITE_PHASE</literal> request phase as a result of
-<link doc="../http/ngx_http_rewrite_module.xml" id="rewrite">rewrite</link> and
+the <link doc="../http/ngx_http_rewrite_module.xml" id="rewrite">rewrite</link>
-return to the <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> phase for choosing a
+directive and send the request back
+to the <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> phase for selection of a
 new location based on the new URI.
 </para>
 <para>
 It is also possible to redirect a request to a new location at any point by
-calling one of the functions
+calling one of
 <literal>ngx_http_internal_redirect(r, uri, args)</literal> or
 <literal>ngx_http_named_location(r, name)</literal>.
 </para>
 <para>
-The function <literal>ngx_http_internal_redirect(r, uri, args)</literal> changes
+The <literal>ngx_http_internal_redirect(r, uri, args)</literal> function changes
 the request URI and returns the request to the
 <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal> phase.
 The request proceeds with a server default location.
 Later at <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> a new location is chosen
 based on the new request URI.
 return ngx_http_named_location(r, &amp;name);
 }
 </programlisting>
 <para>
-Both functions <literal>ngx_http_internal_redirect(r, uri, args)</literal>
+Both functions - <literal>ngx_http_internal_redirect(r, uri, args)</literal>
-and <literal>ngx_http_named_location(r, name)</literal> may be called when
+and <literal>ngx_http_named_location(r, name)</literal> can be called when
-a request already has some contexts saved in its <literal>ctx</literal> field
+nginx modules have already stored some contexts in a request's
-by nginx modules.
+<literal>ctx</literal> field.
-These contexts could become inconsistent with the new
+It's possible for these contexts to become inconsistent with the new
 location configuration.
 To prevent inconsistency, all request contexts are
 erased by both redirect functions.
 </para>
 <para>
-Redirected and rewritten requests become internal and may access the
+Calling <literal>ngx_http_internal_redirect(r, uri, args)</literal>
+or <literal>ngx_http_named_location(r, name)</literal> increases the request
+<literal>count</literal>.
+For consistent request reference counting, call
+<literal>ngx_http_finalize_request(r, NGX_DONE)</literal> after redirecting the
+request.
+This will finalize current request code path and decrease the counter.
+</para>
+<para>
+Redirected and rewritten requests become internal and can access the
 <link doc="../http/ngx_http_core_module.xml" id="internal">internal</link>
 locations.
 Internal requests have the <literal>internal</literal> flag set.
 </para>
 <section name="Subrequests" id="http_subrequests">
 <para>
-Subrequests are primarily used to include output of one request into another,
+Subrequests are primarily used to insert output of one request into another,
 possibly mixed with other data.
 A subrequest looks like a normal request, but shares some data with its parent.
-Particularly, all fields related to client input are shared since a subrequest
+In particular, all fields related to client input are shared
-does not receive any other input from client.
+because a subrequest does not receive any other input from the client.
-The request field <literal>parent</literal> for a subrequest keeps a link to its
+The request field <literal>parent</literal> for a subrequest contains a link
-parent request and is NULL for the main request.
+to its parent request and is NULL for the main request.
-The field <literal>main</literal> keeps a link to the main request in a group of
+The field <literal>main</literal> contains a link to the main request in
-requests.
+a group of requests.
 </para>
 <para>
-A subrequest starts with <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal> phase.
+A subrequest starts in the <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal>
-It passes through the same phases as a normal request and is assigned a location
+phase.
-based on its own URI.
+It passes through the same subsequent phases as a normal request and is
-</para>
+assigned a location based on its own URI.
+</para>
-<para>
-Subrequest output header is always ignored.
+<para>
-Subrequest output body is placed by the
+The output header in a subrequest is always ignored.
-<literal>ngx_http_postpone_filter</literal> into the right position in relation
+The <literal>ngx_http_postpone_filter</literal> places the subrequest's
-to other data produced by the parent request.
+output body in the right position relative to other data produced
+by the parent request.
 </para>
 <para>
 Subrequests are related to the concept of active requests.
 A request <literal>r</literal> is considered active if
 <literal>c->data == r</literal>, where <literal>c</literal> is the client
 connection object.
-At any point, only the active request in a request group is allowed to output
+At any given point, only the active request in a request group is allowed
-its buffers to the client.
+to output its buffers to the client.
-A non-active request can still send its data to the filter chain, but they
+An inactive request can still send its output to the filter chain, but it
-will not pass beyond the <literal>ngx_http_postpone_filter</literal> and will
+does not pass beyond the <literal>ngx_http_postpone_filter</literal> and
-remain buffered by that filter until the request becomes active.
+remains buffered by that filter until the request becomes active.
 Here are some rules of request activation:
 </para>
 <list type="bullet">
 <listitem>
-Initially, the main request is active
+Initially, the main request is active.
 </listitem>
 <listitem>
-The first subrequest of an active request becomes active right after creation
+The first subrequest of an active request becomes active right after creation.
 </listitem>
 <listitem>
 The <literal>ngx_http_postpone_filter</literal> activates the next request
-in active request's subrequest list, once all data prior to that request are
+in the active request's subrequest list, once all data prior to that request
-sent
+are sent.
 </listitem>
 <listitem>
-When a request is finalized, its parent is activated
+When a request is finalized, its parent is activated.
 </listitem>
 </list>
 <para>
-A subrequest is created by calling the function
+Create a subrequest by calling the function
 <literal>ngx_http_subrequest(r, uri, args, psr, ps, flags)</literal>, where
 <literal>r</literal> is the parent request, <literal>uri</literal> and
-<literal>args</literal> are URI and arguments of the
+<literal>args</literal> are the URI and arguments of the
-subrequest, <literal>psr</literal> is the output parameter, receiving the
+subrequest, <literal>psr</literal> is the output parameter, which receives the
 newly created subrequest reference, <literal>ps</literal> is a callback object
-for notifying the parent request that the subrequest is being finalized,
+for notifying the parent request that the subrequest is being finalized, and
-<literal>flags</literal> is subrequest creation flags bitmask.
+<literal>flags</literal> is bitmask of flags.
 The following flags are available:
 </para>
 <list type="bullet">
 <listitem>
-<literal>NGX_HTTP_SUBREQUEST_IN_MEMORY</literal> - subrequest output should not
+<literal>NGX_HTTP_SUBREQUEST_IN_MEMORY</literal> - Output is not
-be sent to the client, but rather stored in memory.
+sent to the client, but rather stored in memory.
-This only works for proxying subrequests.
+The flag only affects subrequests which are processed by one of the proxying
-After subrequest finalization its output is available in
+modules.
-<literal>r->upstream->buffer</literal> buffer of type
+After a subrequest is finalized its output is available in
-<literal>ngx_buf_t</literal>
+a <literal>r->upstream->buffer</literal> of type <literal>ngx_buf_t</literal>.
 </listitem>
 <listitem>
-<literal>NGX_HTTP_SUBREQUEST_WAITED</literal> - the subrequest
+<literal>NGX_HTTP_SUBREQUEST_WAITED</literal> - The subrequest's
-<literal>done</literal> flag is set even if it is finalized being non-active.
+<literal>done</literal> flag is set even if the subrequest is not active when
-This subrequest flag is used by the SSI filter
+it is finalized.
-</listitem>
+This subrequest flag is used by the SSI filter.
+</listitem>
-<listitem>
-<literal>NGX_HTTP_SUBREQUEST_CLONE</literal> - the subrequest is created as a
+<listitem>
+<literal>NGX_HTTP_SUBREQUEST_CLONE</literal> - The subrequest is created as a
 clone of its parent.
 It is started at the same location and proceeds from the same phase as the
-parent request
+parent request.
 </listitem>
 </list>
 <para>
-The following example creates a subrequest with the URI of "/foo".
+The following example creates a subrequest with the URI
+of <literal>/foo</literal>.
 </para>
 <programlisting>
 ngx_int_t            rc;
 ngx_str_t            uri;
 return rc;
 }
 </programlisting>
 <para>
-Subrequests are normally created in a body filter.
+Subrequests are normally created in a body filter, in which case their output
-In this case subrequest output can be treated as any other explicit request
+can be treated like the output from any explicit request.
-output.
+This means that eventually the output of a subrequest is sent to the client,
-This means that eventually the output of a subrequest is sent to the client
+after all explicit buffers that are passed before subrequest creation and
-after all explicit buffers passed prior to subrequest creation and before any
+before any buffers that are passed after creation.
-buffers passed later.
 This ordering is preserved even for large hierarchies of subrequests.
-The following example inserts a subrequest output after all request data
+The following example inserts output from a subrequest after all request data
 buffers, but before the final buffer with the <literal>last_buf</literal> flag.
 </para>
 <programlisting>
 ngx_int_t
 return NGX_ERROR;
 }
 ngx_http_set_ctx(r, NULL, ngx_http_foo_filter_module);
 /* Output the final buffer with the last_buf flag */
 b = ngx_calloc_buf(r->pool);
 if (b == NULL) {
 return NGX_ERROR;
 return ngx_http_output_filter(r, &amp;out);
 }
 </programlisting>
 <para>
-A subrequest may also be created for other purposes than data output.
+A subrequest can also be created for other purposes than data output.
 For example, the <link doc="../http/ngx_http_auth_request_module.xml">
-ngx_http_auth_request_module</link>
+ngx_http_auth_request_module</link> module
-creates a subrequest at <literal>NGX_HTTP_ACCESS_PHASE</literal> phase.
+creates a subrequest at the <literal>NGX_HTTP_ACCESS_PHASE</literal> phase.
-To disable any output at this point, the subrequest
+To disable output at this point, the
-<literal>header_only</literal> flag is set.
+<literal>header_only</literal> flag is set on the subrequest.
-This prevents subrequest body from being sent to the client.
+This prevents the subrequest body from being sent to the client.
-Its header is ignored anyway.
+Note that the subrequest's header is never sent to the client.
 The result of the subrequest can be analyzed in the callback handler.
 </para>
 </section>
 <section name="Request finalization" id="http_request_finalization">
 <para>
 An HTTP request is finalized by calling the function
 <literal>ngx_http_finalize_request(r, rc)</literal>.
-It is usually finalized by the content handler after sending all output buffers
+It is usually finalized by the content handler after all output buffers
-to the filter chain.
+are sent to the filter chain.
-At this point the output may not be completely sent to the client, but remain
+At this point all of the output might not be sent to the client,
-buffered somewhere along the filter chain.
+with some of it remaining buffered somewhere along the filter chain.
-If it is, the <literal>ngx_http_finalize_request(r, rc)</literal> function will
+If it is, the <literal>ngx_http_finalize_request(r, rc)</literal> function
-automatically install a special handler <literal>ngx_http_writer(r)</literal>
+automatically installs a special handler <literal>ngx_http_writer(r)</literal>
 to finish sending the output.
 A request is also finalized in case of an error or if a standard HTTP response
 code needs to be returned to the client.
 </para>
 </para>
 <list type="bullet">
 <listitem>
-<literal>NGX_DONE</literal> - fast finalization.
+<literal>NGX_DONE</literal> - Fast finalization.
-Decrement request <literal>count</literal> and destroy the request if it
+Decrement the request <literal>count</literal> and destroy the request if it
 reaches zero.
-The client connection may still be used for more requests after that
+The client connection can be used for more requests after the current request
+is destroyed.
 </listitem>
 <listitem>
 <literal>NGX_ERROR</literal>, <literal>NGX_HTTP_REQUEST_TIME_OUT</literal>
-(408), <literal>NGX_HTTP_CLIENT_CLOSED_REQUEST</literal> (499) - error
+(<literal>408</literal>), <literal>NGX_HTTP_CLIENT_CLOSED_REQUEST</literal>
-finalization.
+(<literal>499</literal>) - Error finalization.
 Terminate the request as soon as possible and close the client connection.
 </listitem>
 <listitem>
-<literal>NGX_HTTP_CREATED</literal> (201),
+<literal>NGX_HTTP_CREATED</literal> (<literal>201</literal>),
-<literal>NGX_HTTP_NO_CONTENT</literal> (204), codes greater than or equal to
+<literal>NGX_HTTP_NO_CONTENT</literal> (<literal>204</literal>), codes greater
-<literal>NGX_HTTP_SPECIAL_RESPONSE</literal> (300) - special response
+than or equal to <literal>NGX_HTTP_SPECIAL_RESPONSE</literal>
-finalization.
+(<literal>300</literal>) - Special response finalization.
-For these values nginx either sends a default code response page to the client
+For these values nginx either sends to the client a default response page for
-or performs the internal redirect to an
+the code or performs the internal redirect to an
-<link doc="../http/ngx_http_core_module.xml" id="error_page"/> location if it's
+<link doc="../http/ngx_http_core_module.xml" id="error_page"/> location if that
-configured for the code
+is configured for the code.
 </listitem>
 <listitem>
-Other codes are considered success finalization codes and may activate the
+Other codes are considered successful finalization codes and might activate the
 request writer to finish sending the response body.
-Once body is completely sent, request <literal>count</literal> is decremented.
+Once the body is completely sent, the request <literal>count</literal>
-If it reaches zero, the request is destroyed, but the client connection may
+is decremented.
+If it reaches zero, the request is destroyed, but the client connection can
 still be used for other requests.
 If <literal>count</literal> is positive, there are unfinished activities
 within the request, which will be finalized at a later point.
 </listitem>
 <section name="Request body" id="http_request_body">
 <para>
-For dealing with client request body, nginx provides the following functions:
+For dealing with the body of a client request, nginx provides the
 <literal>ngx_http_read_client_request_body(r, post_handler)</literal> and
-<literal>ngx_http_discard_request_body(r)</literal>.
+<literal>ngx_http_discard_request_body(r)</literal> functions.
 The first function reads the request body and makes it available via the
 <literal>request_body</literal> request field.
 The second function instructs nginx to discard (read and ignore) the request
 body.
 One of these functions must be called for every request.
-Normally, it is done in the content handler.
+Normally, the content handler makes the call.
 </para>
 <para>
-Reading or discarding client request body from a subrequest is not allowed.
+Reading or discarding the client request body from a subrequest is not allowed.
-It should always be done in the main request.
+It must always be done in the main request.
-When a subrequest is created, it inherits the parent
+When a subrequest is created, it inherits the parent's
 <literal>request_body</literal> object which can be used by the subrequest if
 the main request has previously read the request body.
 </para>
 <para>
 The function
 <literal>ngx_http_read_client_request_body(r, post_handler)</literal> starts
 the process of reading the request body.
 When the body is completely read, the <literal>post_handler</literal> callback
 is called to continue processing the request.
-If request body is missing or already read, the callback is called immediately.
+If the request body is missing or has already been read, the callback is called
+immediately.
 The function
 <literal>ngx_http_read_client_request_body(r, post_handler)</literal>
 allocates the <literal>request_body</literal> request field of type
 <literal>ngx_http_request_body_t</literal>.
 The field <literal>bufs</literal> of this object keeps the result as a buffer
 chain.
-The body can be saved in memory buffers or file buffers, if
+The body can be saved in memory buffers or file buffers, if the capacity
+specified by the
 <link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/>
-is not enough to fit the entire body in memory.
+directive is not enough to fit the entire body in memory.
 </para>
 <para>
-The following example reads client request body and returns its size.
+The following example reads a client request body and returns its size.
 </para>
 <programlisting>
 ngx_int_t
 ngx_http_foo_content_handler(ngx_http_request_t *r)
 ngx_http_finalize_request(r, rc);
 }
 </programlisting>
 <para>
-The following fields of the request affect the way request body is read:
+The following fields of the request determine how the request body is read:
 </para>
 <list type="bullet">
 <listitem>
-<literal>request_body_in_single_buf</literal> - read body to a single memory
+<literal>request_body_in_single_buf</literal> - Read the body to a single memory
-buffer
+buffer.
 </listitem>
 <listitem>
-<literal>request_body_in_file_only</literal> - always read body to a file,
+<literal>request_body_in_file_only</literal> - Always read the body to a file,
-even if fits the memory buffer
+even if fits in the memory buffer.
 </listitem>
 <listitem>
-<literal>request_body_in_persistent_file</literal> - do not unlink the file
+<literal>request_body_in_persistent_file</literal> - Do not unlink the file
-right after creation.
+immediately after creation.
-Such a file can be moved to another directory
+A file with this flag can be moved to another directory.
 </listitem>
 <listitem>
-<literal>request_body_in_clean_file</literal> - unlink the file the when the
+<literal>request_body_in_clean_file</literal> - Unlink the file when the
 request is finalized.
 This can be useful when a file was supposed to be moved to another directory
-but eventually was not moved for some reason
+but was not moved for some reason.
 </listitem>
 <listitem>
-<literal>request_body_file_group_access</literal> - enable file group access.
+<literal>request_body_file_group_access</literal> - Enable group access to the
-By default a file is created with 0600 access mask.
+file by replacing the default 0600 access mask with 0660.
-When the flag is set, 0660 access mask is used
+</listitem>
-</listitem>
+<listitem>
-<listitem>
+<literal>request_body_file_log_level</literal> - Severity level at which to
-<literal>request_body_file_log_level</literal> - log file errors with this
+log file errors.
-log level
+</listitem>
-</listitem>
+<listitem>
-<listitem>
+<literal>request_body_no_buffering</literal> - Read the request body without
-<literal>request_body_no_buffering</literal> - read request body without
+buffering.
-buffering
+</listitem>
-</listitem>
+</list>
-</list>
+<para>
-<para>
+The <literal>request_body_no_buffering</literal> flag enables the
-When the <literal>request_body_no_buffering</literal> flag is set, the
+unbuffered mode of reading a request body.
-unbuffered mode of reading the request body is enabled.
 In this mode, after calling
 <literal>ngx_http_read_client_request_body()</literal>, the
-<literal>bufs</literal> chain may keep only a part of the body.
+<literal>bufs</literal> chain might keep only a part of the body.
-To read the next part, the
+To read the next part, call the
-<literal>ngx_http_read_unbuffered_request_body(r)</literal> function should be
+<literal>ngx_http_read_unbuffered_request_body(r)</literal> function.
-called.
+The return value <literal>NGX_AGAIN</literal> and the request flag
-The return value of <literal>NGX_AGAIN</literal> and the request flag
 <literal>reading_body</literal> indicate that more data is available.
 If <literal>bufs</literal> is NULL after calling this function, there is
 nothing to read at the moment.
 The request callback <literal>read_event_handler</literal> will be called when
 the next part of request body is available.
 <section name="Response" id="http_response">
 <para>
-An HTTP response in nginx is produced by sending the response header followed by
+In nginx an HTTP response is produced by sending the response header followed by
 the optional response body.
 Both header and body are passed through a chain of filters and eventually get
 written to the client socket.
 An nginx module can install its handler into the header or body filter chain
 and process the output coming from the previous handler.
 <section name="Response header" id="http_response_header">
 <para>
-Output header is sent by the function
+The <literal>ngx_http_send_header(r)</literal>
-<literal>ngx_http_send_header(r)</literal>.
+function sends the output header.
-Prior to calling this function, <literal>r->headers_out</literal> should contain
+Do not call this function until <literal>r->headers_out</literal>
-all the data required to produce the HTTP response header.
+contains all of the data  required to produce the HTTP response header.
-It's always required to set the <literal>status</literal> field of
+The <literal>status</literal> field in <literal>r->headers_out</literal>
-<literal>r->headers_out</literal>.
+must always be set.
-If the response status suggests that a response body follows the header,
+If the response status indicates that a response body follows the header,
 <literal>content_length_n</literal> can be set as well.
-The default value for this field is -1, which means that the body size is
+The default value for this field is <literal>-1</literal>,
-unknown.
+which means that the body size is unknown.
 In this case, chunked transfer encoding is used.
-To output an arbitrary header, <literal>headers</literal> list should be
+To output an arbitrary header, append the <literal>headers</literal> list.
-appended.
 </para>
 <programlisting>
 static ngx_int_t
 ngx_http_foo_content_handler(ngx_http_request_t *r)
 <section name="Header filters" id="http_header_filters">
 <para>
 The <literal>ngx_http_send_header(r)</literal> function invokes the header
-filter chain by calling the top header filter handler
+filter chain by calling the first header filter handler stored in
-<literal>ngx_http_top_header_filter</literal>.
+the <literal>ngx_http_top_header_filter</literal> variable.
-It's assumed that every header handler calls the next handler in chain until
+It's assumed that every header handler calls the next handler in the chain
-the final handler <literal>ngx_http_header_filter(r)</literal> is called.
+until the final handler <literal>ngx_http_header_filter(r)</literal> is called.
 The final header handler constructs the HTTP response based on
 <literal>r->headers_out</literal> and passes it to the
 <literal>ngx_http_writer_filter</literal> for output.
 </para>
 <para>
-To add a handler to the header filter chain, one should store its address in
+To add a handler to the header filter chain, store its address in
-<literal>ngx_http_top_header_filter</literal> global variable at configuration
+the global variable <literal>ngx_http_top_header_filter</literal>
-time.
+at configuration time.
-The previous handler address is normally stored in a module's static variable
+The previous handler address is normally stored in a static variable in a module
 and is called by the newly added handler before exiting.
 </para>
 <para>
-The following is an example header filter module, adding the HTTP header
+The following example of a header filter module adds the HTTP header
-"X-Foo: foo" to every output with the status 200.
+"<literal>X-Foo: foo</literal>" to every response with status
+<literal>200</literal>.
 </para>
 <programlisting>
 #include &lt;ngx_config.h&gt;
 #include &lt;ngx_core.h&gt;
 <section name="Response body" id="http_response_body">
 <para>
-Response body is sent by calling the function
+To send the response body, call the
-<literal>ngx_http_output_filter(r, cl)</literal>.
+<literal>ngx_http_output_filter(r, cl)</literal> function.
 The function can be called multiple times.
-Each time it sends a part of the response body passed as a buffer chain.
+Each time, it sends a part of the response body in the form of a buffer chain.
-The last body buffer should have the <literal>last_buf</literal> flag set.
+Set the <literal>last_buf</literal> flag in the last body buffer.
 </para>
 <para>
-The following example produces a complete HTTP output with "foo" as its body.
+The following example produces a complete HTTP response with "foo" as its body.
-In order for the example to work not only as a main request but as a subrequest
+For the example to work as subrequest as well as a main request,
-as well, the <literal>last_in_chain</literal> flag is set in the last buffer
+the <literal>last_in_chain</literal> flag is set in the last buffer
 of the output.
-The <literal>last_buf</literal> flag is set only for the main request since
+The <literal>last_buf</literal> flag is set only for the main request because
-a subrequest's last buffers does not end the entire output.
+the last buffer for a subrequest does not end the entire output.
 </para>
 <programlisting>
 static ngx_int_t
 ngx_http_bar_content_handler(ngx_http_request_t *r)
 <section name="Body filters" id="http_body_filters">
 <para>
 The function <literal>ngx_http_output_filter(r, cl)</literal> invokes the
-body filter chain by calling the top body filter handler
+body filter chain by calling the first body filter handler stored in
-<literal>ngx_http_top_body_filter</literal>.
+the <literal>ngx_http_top_body_filter</literal> variable.
-It's assumed that every body handler calls the next handler in chain until
+It's assumed that every body handler calls the next handler in the chain until
 the final handler <literal>ngx_http_write_filter(r, cl)</literal> is called.
 </para>
 <para>
 A body filter handler receives a chain of buffers.
 The handler is supposed to process the buffers and pass a possibly new chain to
 the next handler.
 It's worth noting that the chain links <literal>ngx_chain_t</literal> of the
-incoming chain belong to the caller.
+incoming chain belong to the caller, and must not be reused or changed.
-They should never be reused or changed.
 Right after the handler completes, the caller can use its output chain links
 to keep track of the buffers it has sent.
-To save the buffer chain or to substitute some buffers before sending further,
+To save the buffer chain or to substitute some buffers before passing to the
-a handler should allocate its own chain links.
+next filter, a handler needs to allocate its own chain links.
 </para>
 <para>
-Following is the example of a simple body filter counting the number of
+Following is an example of a simple body filter that counts the number of
-body bytes.
+bytes in the body.
 The result is available as the <literal>$counter</literal> variable which can be
 used in the access log.
 </para>
 <programlisting>
 <section name="Building filter modules" id="http_building_filter_modules">
 <para>
-When writing a body or header filter, a special care should be taken of the
+When writing a body or header filter, pay special attention to the filter's
-filters order.
+position in the filter order.
 There's a number of header and body filters registered by nginx standard
 modules.
-It's important to register a filter module in the right place in respect to
+The nginx standard modules register a number of head and body filters and it's
-other filters.
+important to register a new filter module in the right place with respect to
-Normally, filters are registered by modules in their postconfiguration handlers.
+them.
-The order in which filters are called is obviously the reverse of when they are
+Normally, modules register filters in their postconfiguration handlers.
-registered.
+The order in which filters are called during processing is obviously the
-</para>
+reverse of the order in which they are registered.
+</para>
-<para>
-A special slot <literal>HTTP_AUX_FILTER_MODULES</literal> for third-party filter
+<para>
-modules is provided by nginx.
+For third-party filter modules nginx provides a special slot
-To register a filter module in this slot, the <literal>ngx_module_type</literal>
+<literal>HTTP_AUX_FILTER_MODULES</literal>.
-variable should be set to the value of <literal>HTTP_AUX_FILTER</literal> in
+To register a filter module in this slot, set
-module's configuration.
+the <literal>ngx_module_type</literal> variable to
-</para>
+<literal>HTTP_AUX_FILTER</literal> in the module's configuration.
+</para>
-<para>
-The following example shows a filter module config file assuming it only has
+<para>
-one source file <literal>ngx_http_foo_filter_module.c</literal>
+The following example shows a filter module config file assuming
+for a module with just
+one source file, <literal>ngx_http_foo_filter_module.c</literal>.
 </para>
 <programlisting>
 ngx_module_type=HTTP_AUX_FILTER
 ngx_module_name=ngx_http_foo_filter_module
 <section name="Buffer reuse" id="http_body_buffers_reuse">
 <para>
 When issuing or altering a stream of buffers, it's often desirable to reuse the
 allocated buffers.
-A standard approach widely adopted in nginx code is to keep two buffer chains
+A standard and widely adopted approach in nginx code is to keep
-for this purpose: <literal>free</literal> and <literal>busy</literal>.
+two buffer chains for this purpose:
-The <literal>free</literal> chain keeps all free buffers.
+<literal>free</literal> and <literal>busy</literal>.
-These buffers can be reused.
+The <literal>free</literal> chain keeps all free buffers,
+which can be reused.
 The <literal>busy</literal> chain keeps all buffers sent by the current
-module which are still in use by some other filter handler.
+module that are still in use by some other filter handler.
 A buffer is considered in use if its size is greater than zero.
 Normally, when a buffer is consumed by a filter, its <literal>pos</literal>
 (or <literal>file_pos</literal> for a file buffer) is moved towards
 <literal>last</literal> (<literal>file_last</literal> for a file buffer).
 Once a buffer is completely consumed, it's ready to be reused.
-To update the <literal>free</literal> chain with newly freed buffers,
+To add newly freed buffers to the <literal>free</literal> chain
 it's enough to iterate over the <literal>busy</literal> chain and move the zero
 size buffers at the head of it to <literal>free</literal>.
-This operation is so common that there is a special function
+This operation is so common that there is a special function for it,
-<literal>ngx_chain_update_chains(free, busy, out, tag)</literal> which does
+<literal>ngx_chain_update_chains(free, busy, out, tag)</literal>.
-this.
 The function appends the output chain <literal>out</literal> to
 <literal>busy</literal> and moves free buffers from the top of
 <literal>busy</literal> to <literal>free</literal>.
-Only the buffers with the given <literal>tag</literal> are reused.
+Only the buffers with the specified <literal>tag</literal> are reused.
-This lets a module reuse only the buffers allocated by itself.
+This lets a module reuse only the buffers that it allocated itself.
 </para>
 <para>
-The following example is a body filter inserting the “foo” string before each
+The following example is a body filter that inserts the string “foo” before each
 incoming buffer.
 The new buffers allocated by the module are reused if possible.
-Note that for this example to work properly, it's also required to set up a
+Note that for this example to work properly, setting up a
-header filter and reset <literal>content_length_n</literal> to -1, which is
+<link id="http_header_filters">header filter</link>
-beyond the scope of this section.
+and resetting <literal>content_length_n</literal> to <literal>-1</literal>
+is also required, but the relevant code is not provided here.
 </para>
 <programlisting>
 typedef struct {
 ngx_chain_t  *free;
 <section name="Load balancing" id="http_load_balancing">
 <para>
 The
 <link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link>
-provides basic functionality to pass requests to remote servers.
+provides the basic functionality needed to pass requests to remote servers.
-This functionality is used by modules that implement specific protocols,
+Modules that implement specific protocols, such as HTTP or FastCGI, use
-such as HTTP or FastCGI.
+this functionality.
 The module also provides an interface for creating custom
-load balancing modules and implements a default round-robin balancing method.
+load-balancing modules and implements a default round-robin method.
 </para>
 <para>
-Examples of modules that implement alternative load balancing methods are
+The <link doc="../http/ngx_http_upstream_module.xml" id="least_conn"/>
-<link doc="../http/ngx_http_upstream_module.xml" id="least_conn"/>
+and <link doc="../http/ngx_http_upstream_module.xml" id="hash"/>
-and <link doc="../http/ngx_http_upstream_module.xml" id="hash"/>.
+modules implement alternative load-balancing methods, but
-Note that these modules are actually implemented as extensions of the upstream
+are actually implemented as extensions of the upstream round-robin
-module and share a lot of code, such as representation of a server group.
+module and share a lot of code with it, such as the representation
+of a server group.
 The <link doc="../http/ngx_http_upstream_module.xml" id="keepalive"/> module
-is an example of an independent module, extending upstream functionality.
+is an independent module that extends upstream functionality.
 </para>
 <para>
 The
 <link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link>
-may be configured explicitly by placing the corresponding
+can be configured explicitly by placing the corresponding
 <link doc="../http/ngx_http_upstream_module.xml" id="upstream"/> block into
 the configuration file, or implicitly by using directives
-that accept a URL evaluated at some point to the list of servers,
+such as <link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/>
-for example,
+that accept a URL that gets evaluated at some point into a list of servers.
-<link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/>.
+The alternative load-balancing methods are available only with an explicit
-Only explicit configurations may use an alternative load balancing method.
+upstream configuration.
 The upstream module configuration has its own directive context
 <literal>NGX_HTTP_UPS_CONF</literal>.
 The structure is defined as follows:
 <programlisting>
 struct ngx_http_upstream_srv_conf_s {
 </programlisting>
 <list type="bullet">
 <listitem>
-<literal>srv_conf</literal> — configuration context of upstream modules
+<literal>srv_conf</literal> — Configuration context of upstream modules.
 </listitem>
 <listitem>
-<literal>servers</literal> — array of
+<literal>servers</literal> — Array of
 <literal>ngx_http_upstream_server_t</literal>, the result of parsing a set of
 <link doc="../http/ngx_http_upstream_module.xml" id="server"/> directives
-in the <literal>upstream</literal> block
+in the <literal>upstream</literal> block.
 </listitem>
 <listitem>
-<literal>flags</literal> — flags that mostly mark which features
+<literal>flags</literal> — Flags that mostly mark which features
-(configured as parameters of
+are supported by the load-balancing method.
-the <link doc="../http/ngx_http_upstream_module.xml" id="server"/> directive)
+The features are configured as parameters of
-are supported by the particular load balancing method.
+the <link doc="../http/ngx_http_upstream_module.xml" id="server"/> directive:
-<list type="bullet">
+<list type="bullet">
-<listitem>
-<literal>NGX_HTTP_UPSTREAM_CREATE</literal> — used to distinguish explicitly
+<listitem>
-defined upstreams from automatically created by
+<literal>NGX_HTTP_UPSTREAM_CREATE</literal> — Distinguishes explicitly
-<link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/> and “friends”
+defined upstreams from those that are automatically created by the
+<link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/> directive
+and “friends”
 (FastCGI, SCGI, etc.)
 </listitem>
 <listitem>
-<literal>NGX_HTTP_UPSTREAM_WEIGHT</literal> — “<literal>weight</literal>”
+<literal>NGX_HTTP_UPSTREAM_WEIGHT</literal> — The “<literal>weight</literal>”
-is supported
+parameter is supported
 </listitem>
 <listitem>
-<literal>NGX_HTTP_UPSTREAM_MAX_FAILS</literal> — “<literal>max_fails</literal>”
+<literal>NGX_HTTP_UPSTREAM_MAX_FAILS</literal> — The
-is supported
+“<literal>max_fails</literal>” parameter is supported
 </listitem>
 <listitem>
 <literal>NGX_HTTP_UPSTREAM_FAIL_TIMEOUT</literal> —
-“<literal>fail_timeout</literal>” is supported
+The “<literal>fail_timeout</literal>” parameter is supported
 </listitem>
 <listitem>
-<literal>NGX_HTTP_UPSTREAM_DOWN</literal> — “<literal>down</literal>”
+<literal>NGX_HTTP_UPSTREAM_DOWN</literal> — The “<literal>down</literal>”
-is supported
+parameter is supported
 </listitem>
 <listitem>
-<literal>NGX_HTTP_UPSTREAM_BACKUP</literal> — “<literal>backup</literal>”
+<literal>NGX_HTTP_UPSTREAM_BACKUP</literal> — The “<literal>backup</literal>”
-is supported
+parameter is supported
 </listitem>
 <listitem>
-<literal>NGX_HTTP_UPSTREAM_MAX_CONNS</literal> — “<literal>max_conns</literal>”
+<literal>NGX_HTTP_UPSTREAM_MAX_CONNS</literal> — The
-is supported
+“<literal>max_conns</literal>” parameter is supported
 </listitem>
 </list>
 </listitem>
 <listitem>
-<literal>host</literal> — the name of an upstream
+<literal>host</literal> — Name of the upstream.
 </listitem>
 <listitem>
-<literal>file_name, line</literal> — the name of the configuration file
+<literal>file_name, line</literal> — Name of the configuration file
-and the line where the <literal>upstream</literal> block is located
+and the line where the <literal>upstream</literal> block is located.
 </listitem>
 <listitem>
-<literal>port</literal> and <literal>no_port</literal> — unused by explicit
+<literal>port</literal> and <literal>no_port</literal> — Not used for
-upstreams
+explicitly defined upstream groups.
 </listitem>
 <listitem>
-<literal>shm_zone</literal> — a shared memory zone used by this upstream, if any
+<literal>shm_zone</literal> — Shared memory zone used by this upstream group,
-</listitem>
+if any.
+</listitem>
-<listitem>
-<literal>peer</literal> — an object that holds generic methods for
+<listitem>
+<literal>peer</literal> — object that holds generic methods for
 initializing upstream configuration:
 <programlisting>
 typedef struct {
 ngx_http_upstream_init_pt        init_upstream;
 ngx_http_upstream_init_peer_pt   init;
 void                            *data;
 } ngx_http_upstream_peer_t;
 </programlisting>
-A module that implements a load balancing algorithm must set these
+A module that implements a load-balancing algorithm must set these
 methods and initialize private <literal>data</literal>.
 If <literal>init_upstream</literal> was not initialized during configuration
-parsing, <literal>ngx_http_upstream_module</literal> sets it to default
+parsing, <literal>ngx_http_upstream_module</literal> sets it to the default
-<literal>ngx_http_upstream_init_round_robin</literal>.
+<literal>ngx_http_upstream_init_round_robin</literal> algorithm.
 <list type="bullet">
 <listitem>
-<literal>init_upstream(cf, us)</literal> — configuration-time
+<literal>init_upstream(cf, us)</literal> — Configuration-time
 method responsible for initializing a group of servers and
 initializing the <literal>init()</literal> method in case of success.
-A typical load balancing module uses a list of servers in the upstream block
+A typical load-balancing module uses a list of servers in the
-to create some efficient data structure that it uses and saves own
+<literal>upstream</literal> block
+to create an efficient data structure that it uses and saves its own
 configuration to the <literal>data</literal> field.
 </listitem>
 <listitem>
-<literal>init(r, us)</literal> — initializes per-request
+<literal>init(r, us)</literal> — Initializes a per-request
-<literal>ngx_http_upstream_peer_t.peer</literal> (not to be confused with the
+<literal>ngx_http_upstream_peer_t.peer</literal> structure that is used for
+load balancing (not to be confused with the
 <literal>ngx_http_upstream_srv_conf_t.peer</literal> described above which
-is per-upstream) structure that is used for load balancing.
+is per-upstream).
-It will be passed as <literal>data</literal> argument to all callbacks that
+It is passed as the <literal>data</literal> argument to all callbacks that
 deal with server selection.
 </listitem>
 </list>
 </listitem>
 </list>
 </para>
 <para>
 When nginx has to pass a request to another host for processing, it uses
-a configured load balancing method to obtain an address to connect to.
+the configured load-balancing method to obtain an address to connect to.
-The method is taken from the
+The method is obtained from the
 <literal>ngx_http_upstream_t.peer</literal> object
 of type <literal>ngx_peer_connection_t</literal>:
 <programlisting>
 struct ngx_peer_connection_s {
-[...]
+...
 struct sockaddr                 *sockaddr;
 socklen_t                        socklen;
 ngx_str_t                       *name;
 #if (NGX_SSL || NGX_COMPAT)
 ngx_event_set_peer_session_pt    set_session;
 ngx_event_save_peer_session_pt   save_session;
 #endif
-[..]
+...
 };
 </programlisting>
 The structure has the following fields:
 <list type="bullet">
 <listitem>
 <literal>sockaddr</literal>, <literal>socklen</literal>,
-<literal>name</literal> — address of an upstream server to connect to;
+<literal>name</literal> — Address of the upstream server to connect to;
-this is the output parameter of a load balancing method
+this is the output parameter of a load-balancing method.
 </listitem>
 <listitem>
-<literal>data</literal> — per-request load balancing method data; keeps the
+<literal>data</literal> — The per-request data of a load-balancing method;
-state of selection algorithm and usually includes the link to upstream
+keeps the state of the selection algorithm and usually includes the link
-configuration.
+to the upstream configuration.
-It will be passed as an argument to all methods that deal with server selection
+It is passed as an argument to all methods that deal with server selection
-(see below)
+(see <link id="lb_method_get">below</link>).
 </listitem>
 <listitem>
-<literal>tries</literal> — allowed
+<literal>tries</literal> — Allowed
 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_next_upstream_tries">number</link>
-of attempts to connect to an upstream.
+of attempts to connect to an upstream server.
 </listitem>
 <listitem>
 <literal>get</literal>, <literal>free</literal>, <literal>notify</literal>,
 <literal>set_session</literal>, and <literal>save_session</literal>
-- methods of the load balancing module, see description below
+- Methods of the load-balancing module, described below.
 </listitem>
 </list>
 </para>
 <para>
-All methods accept at least two arguments: peer connection object
+All methods accept at least two arguments: a peer connection object
 <literal>pc</literal> and the <literal>data</literal> created by
 <literal>ngx_http_upstream_srv_conf_t.peer.init()</literal>.
-Note that in general case it may differ from <literal>pc.data</literal> due
+Note that it might differ from <literal>pc.data</literal> due
-to “chaining” of load balancing modules.
+to “chaining” of load-balancing modules.
 </para>
 <para>
 <list type="bullet">
-<listitem>
+<listitem id="lb_method_get">
-<literal>get(pc, data)</literal> — the method is called when the upstream
+<literal>get(pc, data)</literal> — The method called when the upstream
 module is ready to pass a request to an upstream server and needs to know
 its address.
-The method is responsible to fill in the <literal>sockaddr</literal>,
+The method has to fill the <literal>sockaddr</literal>,
 <literal>socklen</literal>, and <literal>name</literal> fields of
 <literal>ngx_peer_connection_t</literal> structure.
-The return value may be one of:
+The return is one of:
 <list type="bullet">
 <listitem>
-<literal>NGX_OK</literal> — server was selected
+<literal>NGX_OK</literal> — Server was selected.
 </listitem>
 <listitem>
-<literal>NGX_ERROR</literal> — internal error occurred
+<literal>NGX_ERROR</literal> — Internal error occurred.
 </listitem>
 <listitem>
-<literal>NGX_BUSY</literal> — there are no available servers at the moment.
+<literal>NGX_BUSY</literal> — no servers are currently available.
-This can happen due to many reasons, such as: dynamic server group is empty,
+This can happen due to many reasons, including: the dynamic server group is
-all servers in the group are in the failed state,
+empty, all servers in the group are in the failed state, or
 all servers in the group are already
-handling the maximum number of connections or similar.
+handling the maximum number of connections.
 </listitem>
 <listitem>
-<literal>NGX_DONE</literal> — this is set by the <literal>keepalive</literal>
+<literal>NGX_DONE</literal> — the underlying connection was reused and there
-module to indicate that the underlying connection was reused and there is no
+is no need to create a new connection to the upstream server.
-need to create a new connection to the upstream server.
+This value is set by the <literal>keepalive</literal> module.
 </listitem>
 <!--
 <listitem>
-<literal>NGX_ABORT</literal> — this is set by the <literal>queue</literal>
+<literal>NGX_ABORT</literal> — the request was queued and the further
-module to indicate that the request was queued and the further processing
+processing of this request should be postponed.
-of this request should be postponed.
+This value is set by the <literal>queue</literal> module.
 </listitem>
 -->
 </list>
 </listitem>
 <listitem>
-<literal>free(pc, data, state)</literal> — the method is called when an
+<literal>free(pc, data, state)</literal> — The method called when an
 upstream module has finished work with a particular server.
-The <literal>state</literal> argument is the status of upstream connection
+The <literal>state</literal> argument is the completion status of the upstream
-completion.
+connection, a bitmask with the following possible values:
-This is a bitmask, the following values may be set:
-<literal>NGX_PEER_FAILED</literal> — this attempt is considered
+<list type="bullet">
-<link doc="../http/ngx_http_upstream_module.xml" id="max_fails">unsuccessful</link>,
-<literal>NGX_PEER_NEXT</literal> — a special case with codes 403 and 404
+<listitem>
-(see link above), which are not considered a failure.
+<literal>NGX_PEER_FAILED</literal> — Attempt was
-<literal>NGX_PEER_KEEPALIVE</literal>.
+<link doc="../http/ngx_http_upstream_module.xml" id="max_fails">unsuccessful</link>
-Also, <literal>tries</literal> counter is decremented by this method.
+</listitem>
-</listitem>
+<listitem>
-<listitem>
+<literal>NGX_PEER_NEXT</literal> — A special case when upstream server
-<literal>notify(pc, data, type)</literal> — currently unused
+returns codes <literal>403</literal> or <literal>404</literal>,
+which are not considered a
+<link doc="../http/ngx_http_upstream_module.xml" id="max_fails">failure</link>.
+</listitem>
+<listitem>
+<literal>NGX_PEER_KEEPALIVE</literal> — Currently unused
+</listitem>
+</list>
+This method also decrements the <literal>tries</literal> counter.
+</listitem>
+<listitem>
+<literal>notify(pc, data, type)</literal> — Currently unused
 in the OSS version.
 </listitem>
 <listitem>
 <literal>set_session(pc, data)</literal> and
 <literal>save_session(pc, data)</literal>
-— SSL-specific methods that allow to cache sessions to upstream
+— SSL-specific methods that enable caching sessions to upstream
 servers.
 The implementation is provided by the round-robin balancing method.
 </listitem>
 </list>

Mercurial > hg > nginx-site

comparison xml/en/docs/dev/development_guide.xml @ 2007:c559be34257b