<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">

<article name="Development guide"
         link="/en/docs/dev/development_guide.html"
         lang="en"
         rev="2">

<section name="Introduction" id="introduction">


<section name="Code layout" id="code_layout">

<para>
<list type="bullet">
<listitem>
<literal>auto</literal> — build scripts
</listitem>

<listitem>
 <literal>src</literal>

<list type="bullet">

<listitem>
<literal>core</literal> — basic types and functions — string, array, log,
pool etc
</listitem>

<listitem>
<literal>event</literal> — event core

<list type="bullet">

<listitem>
<literal>modules</literal> — event notification modules: epoll, kqueue,
select etc
</listitem>

</list>

</listitem>

<listitem>
<literal>http</literal> — core HTTP module and common code

<list type="bullet">

<listitem>
<literal>modules</literal> — other HTTP modules
</listitem>

<listitem>
<literal>v2</literal> — HTTPv2
</listitem>

</list>

</listitem>

<listitem>
<literal>mail</literal> — mail modules
</listitem>

<listitem>
<literal>os</literal> — platform-specific code

<list type="bullet">

<listitem>
 <literal>unix</literal>
</listitem>

<listitem>
 <literal>win32</literal>
</listitem>

</list>

</listitem>

<listitem>
<literal>stream</literal> — stream modules
</listitem>

</list>

</listitem>

</list>
</para>

</section>


<section name="Include files" id="include_files">

<para>
Each nginx file should start with including the following two files:
</para>


<programlisting>
#include &lt;ngx_config.h>
#include &lt;ngx_core.h>
</programlisting>

<para>
In addition to that, HTTP code should include
</para>


<programlisting>
#include &lt;ngx_http.h>
</programlisting>

<para>
Mail code should include
</para>


<programlisting>
#include &lt;ngx_mail.h>
</programlisting>

<para>
Stream code should include
</para>


<programlisting>
#include &lt;ngx_stream.h>
</programlisting>

</section>


<section name="Integers" id="integers">

<para>
For general purpose, nginx code uses the following two integer types
<literal>ngx_int_t</literal> and <literal>ngx_uint_t</literal> which are
typedefs for <literal>intptr_t</literal> and <literal>uintptr_t</literal>.
</para>

</section>


<section name="Common return codes" id="common_return_codes">

<para>
Most functions in nginx return the following codes:
</para>

<para>
<list type="bullet">

<listitem>
<literal>NGX_OK</literal> — operation succeeded
</listitem>

<listitem>
<literal>NGX_ERROR</literal> — operation failed
</listitem>

<listitem>
<literal>NGX_AGAIN</literal> — operation incomplete, function should be called
again
</listitem>

<listitem>
<literal>NGX_DECLINED</literal> — operation rejected, for example, if disabled
in configuration. This is never an error
</listitem>

<listitem>
<literal>NGX_BUSY</literal> — resource is not available
</listitem>

<listitem>
<literal>NGX_DONE</literal> — operation done or continued elsewhere.
Also used as an alternative success code
</listitem>

<listitem>
<literal>NGX_ABORT</literal> — function was aborted.
Also used as an alternative error code
</listitem>

</list>
</para>

</section>


<section name="Error handling" id="error_handling">

<para>
For getting the last system error code, the <literal>ngx_errno</literal> macro
is available.
It's mapped to <literal>errno</literal> on POSIX platforms and to
<literal>GetLastError()</literal> call in Windows.
For getting the last socket error number, the
<literal>ngx_socket_errno</literal> macro is available.
It's mapped to <literal>errno</literal> on POSIX systems as well,
and to <literal>WSAGetLastError()</literal> call on Windows.
For performance reasons the values of <literal>ngx_errno</literal> or
<literal>ngx_socket_errno</literal> should not be accessed more than
once in a row.
The error value should be stored in a local variable of type
<literal>ngx_err_t</literal> for using multiple times, if required.
For setting errors, <literal>ngx_set_errno(errno)</literal> and
<literal>ngx_set_socket_errno(errno)</literal> macros are available.
</para>

<para>
The values of <literal>ngx_errno</literal> or
<literal>ngx_socket_errno</literal> can be passed to logging functions
<literal>ngx_log_error()</literal> and <literal>ngx_log_debugX()</literal>, in
which case system error text is added to the log message.
</para>

<para>
Example using <literal>ngx_errno</literal>:
</para>


<programlisting>
void
ngx_my_kill(ngx_pid_t pid, ngx_log_t *log, int signo)
{
    ngx_err_t  err;

    if (kill(pid, signo) == -1) {
        err = ngx_errno;

        ngx_log_error(NGX_LOG_ALERT, log, err, "kill(%P, %d) failed", pid, signo);

        if (err == NGX_ESRCH) {
            return 2;
        }

        return 1;
    }

    return 0;
}
</programlisting>

</section>


</section>


<section name="Strings" id="strings">


<section name="Overview" id="overview">

<para>
For C strings, nginx code uses unsigned character type pointer
<literal>u_char *</literal>.
</para>

<para>
The nginx string type <literal>ngx_str_t</literal> is defined as follows:
</para>


<programlisting>
typedef struct {
    size_t      len;
    u_char     *data;
} ngx_str_t;
</programlisting>

<para>
The <literal>len</literal> field holds the string length,
<literal>data</literal> holds the string data.
The string, held in <literal>ngx_str_t</literal>, may or may not be
null-terminated after the <literal>len</literal> bytes.
In most cases it’s not.
However, in certain parts of code (for example, when parsing configuration),
<literal>ngx_str_t</literal> objects are known to be null-terminated, and that
knowledge is used to simplify string comparison and makes it easier to pass
those strings to syscalls.
</para>

<para>
A number of string operations are provided in nginx.
They are declared in <path>src/core/ngx_string.h</path>.
Some of them are wrappers around standard C functions:
</para>

<para>
<list type="bullet">

<listitem>
<literal>ngx_strcmp()</literal>
</listitem>

<listitem>
<literal>ngx_strncmp()</literal>
</listitem>

<listitem>
<literal>ngx_strstr()</literal>
</listitem>

<listitem>
<literal>ngx_strlen()</literal>
</listitem>

<listitem>
<literal>ngx_strchr()</literal>
</listitem>

<listitem>
<literal>ngx_memcmp()</literal>
</listitem>

<listitem>
<literal>ngx_memset()</literal>
</listitem>

<listitem>
<literal>ngx_memcpy()</literal>
</listitem>

<listitem>
<literal>ngx_memmove()</literal>
</listitem>

</list>

</para>

<para>
Some nginx-specific string functions:
</para>

<para>
<list type="bullet">

<listitem>
<literal>ngx_memzero()</literal> fills memory with zeroes
</listitem>

<listitem>
<literal>ngx_cpymem()</literal> does the same as
<literal>ngx_memcpy()</literal>, but returns the final destination address
This one is handy for appending multiple strings in a row
</listitem>

<listitem>
<literal>ngx_movemem()</literal> does the same as
<literal>ngx_memmove()</literal>, but returns the final destination address.
</listitem>

<listitem>
<literal>ngx_strlchr()</literal> searches for a character in a string,
delimited by two pointers
</listitem>
</list>
</para>

<para>
Some case conversion and comparison functions:
</para>

<para>
<list type="bullet">

<listitem>
 <literal>ngx_tolower()</literal>
</listitem>

<listitem>
 <literal>ngx_toupper()</literal>
</listitem>

<listitem>
 <literal>ngx_strlow()</literal>
</listitem>

<listitem>
 <literal>ngx_strcasecmp()</literal>
</listitem>

<listitem>
 <literal>ngx_strncasecmp()</literal>
</listitem>

</list>
</para>

</section>


<section name="Formatting" id="formatting">

<para>
A number of formatting functions are provided by nginx.  These functions support nginx-specific types:
</para>


<para>
<list type="bullet">

<listitem>
<literal>ngx_sprintf(buf, fmt, ...)</literal>
</listitem>

<listitem>
<literal>ngx_snprintf(buf, max, fmt, ...)</literal>
</listitem>

<listitem>
<literal>ngx_slrintf(buf, last, fmt, ...)</literal>
</listitem>

<listitem>
<literal>ngx_vslprint(buf, last, fmt, args)</literal>
</listitem>

<listitem>
<literal>ngx_vsnprint(buf, max, fmt, args)</literal>
</listitem>

</list>
</para>

<para>
The full list of formatting options, supported by these functions, can be found
in <path>src/core/ngx_string.c</path>. Some of them are:
</para>


<programlisting>
%O — off_t
%T — time_t
%z — size_t
%i — ngx_int_t
%p — void *
%V — ngx_str_t *
%s — u_char * (null-terminated)
%*s — size_t + u_char *
</programlisting>

<para>
The ‘u’ modifier makes most types unsigned, ‘X’/‘x’ convert output to hex.
</para>

<para>
Example:

<programlisting>
u_char     buf[NGX_INT_T_LEN];
size_t     len;
ngx_int_t  n;

/* set n here */

len = ngx_sprintf(buf, "%ui", n) — buf;
</programlisting>

</para>

</section>


<section name="Numeric conversion" id="numeric_conversion">

<para>
Several functions for numeric conversion are implemented in nginx:
</para>

<para>
<list type="bullet">

<listitem>
<literal>ngx_atoi(line, n)</literal> — converts a string of given length to a
positive integer of type <literal>ngx_int_t</literal>.
Returns <literal>NGX_ERROR</literal> on error
</listitem>

<listitem>
<literal>ngx_atosz(line, n)</literal> — same for <literal>ssize_t</literal>
type
</listitem>

<listitem>
<literal>ngx_atoof(line, n)</literal> — same for <literal>off_t</literal>
type
</listitem>

<listitem>
<literal>ngx_atotm(line, n)</literal> — same for <literal>time_t</literal>
type
</listitem>

<listitem>
<literal>ngx_atofp(line, n, point)</literal> — converts a fixed point floating
number of given length to a positive integer of type
<literal>ngx_int_t</literal>.
The result is shifted left by <literal>points</literal> decimal
positions. The string representation of the number is expected to have no more
than <literal>points</literal> fractional digits.
Returns <literal>NGX_ERROR</literal> on error. For example,
<literal>ngx_atofp("10.5", 4, 2)</literal> returns <literal>1050</literal>
</listitem>

<listitem>
<literal>ngx_hextoi(line, n)</literal> — converts hexadecimal representation of
a positive integer to <literal>ngx_int_t</literal>. Returns
<literal>NGX_ERROR</literal> on error
</listitem>

</list>
</para>

</section>

<section name="Regular expressions" id="regex">

<para>
The regular expressions interface in nginx is a wrapper around
the <link url="http://www.pcre.org">PCRE</link>
library.
The corresponding header file is <path>src/core/ngx_regex.h</path>.
</para>

<para>
To use a regular expression for string matching, first, it needs to be
compiled, this is usually done at configuration phase.
Note that since PCRE support is optional, all code using the interface must
be protected by the surrounding <literal>NGX_PCRE</literal> macro:
<programlisting>
#if (NGX_PCRE)
ngx_regex_t          *re;
ngx_regex_compile_t   rc;

u_char                errstr[NGX_MAX_CONF_ERRSTR];

ngx_str_t  value = ngx_string("message (\\d\\d\\d).*Codeword is '(?&lt;cw&gt;\\w+)'");

ngx_memzero(&amp;rc, sizeof(ngx_regex_compile_t));

rc.pattern = value;
rc.pool = cf->pool;
rc.err.len = NGX_MAX_CONF_ERRSTR;
rc.err.data = errstr;
/* rc.options are passed as is to pcre_compile() */

if (ngx_regex_compile(&amp;rc) != NGX_OK) {
    ngx_conf_log_error(NGX_LOG_EMERG, cf, 0, "%V", &amp;rc.err);
    return NGX_CONF_ERROR;
}

re = rc.regex;
#endif
</programlisting>
After successful compilation, <literal>ngx_regex_compile_t</literal> structure
fields <literal>captures</literal> and <literal>named_captures</literal>
are filled with count of all and named captures respectively found in the
regular expression.
</para>

<para>
Later, the compiled regular expression may be used to match strings against it:
<programlisting>
ngx_int_t  n;
int        captures[(1 + rc.captures) * 3];

ngx_str_t input = ngx_string("This is message 123. Codeword is 'foobar'.");

n = ngx_regex_exec(re, &amp;input, captures, (1 + rc.captures) * 3);
if (n >= 0) {
    /* string matches expression */

} else if (n == NGX_REGEX_NO_MATCHED) {
    /* no match was found */

} else {
    /* some error */
    ngx_log_error(NGX_LOG_ALERT, log, 0, ngx_regex_exec_n " failed: %i", n);
}
</programlisting>
The arguments of <literal>ngx_regex_exec()</literal> are: the compiled regular
expression <literal>re</literal>, string to match <literal>s</literal>,
optional array of integers to hold found <literal>captures</literal>
and its <literal>size</literal>.
The <literal>captures</literal> array size  must be a multiple of three,
per requirements of the
<link url="http://www.pcre.org/original/doc/html/pcreapi.html">PCRE API</link>.
In the example, its size is calculated from a total number of captures plus
one for the matched string itself.
</para>

<para>
Now, if there are matches, captures may be accessed:
<programlisting>
u_char     *p;
size_t      size;
ngx_str_t   name, value;

/* all captures */
for (i = 0; i &lt; n * 2; i += 2) {
    value.data = input.data + captures[i];
    value.len = captures[i + 1] — captures[i];
}

/* accessing named captures */

size = rc.name_size;
p = rc.names;

for (i = 0; i &lt; rc.named_captures; i++, p += size) {

    /* capture name */
    name.data = &amp;p[2];
    name.len = ngx_strlen(name.data);

    n = 2 * ((p[0] &lt;&lt; 8) + p[1]);

    /* captured value */
    value.data = &amp;input.data[captures[n]];
    value.len = captures[n + 1] — captures[n];
}
</programlisting>
</para>

<para>
The <literal>ngx_regex_exec_array()</literal> function accepts the array of
<literal>ngx_regex_elt_t</literal> elements (which are just compiled regular
expressions with associated names), a string to match and a log.
The function will apply expressions from the array to the string until
the match is found or no more expressions are left.
The return value is <literal>NGX_OK</literal> in case of match and
<literal>NGX_DECLINED</literal> otherwise, or <literal>NGX_ERROR</literal>
in case of error.
</para>

</section>

</section>


<section name="Containers" id="containers">


<section name="Array" id="array">

<para>
The nginx array type <literal>ngx_array_t</literal> is defined as follows
</para>


<programlisting>
typedef struct {
    void        *elts;
    ngx_uint_t   nelts;
    size_t       size;
    ngx_uint_t   nalloc;
    ngx_pool_t  *pool;
} ngx_array_t;
</programlisting>

<para>
The elements of array are available through the <literal>elts</literal> field.
The number of elements is held in the <literal>nelts</literal> field.
The <literal>size</literal> field holds the size of a single element and is set
when initializing the array.
</para>

<para>
An array can be created in a pool with the
<literal>ngx_array_create(pool, n, size)</literal> call.
An already allocated array object can be initialized with the
<literal>ngx_array_init(array, pool, n, size)</literal> call.
</para>


<programlisting>
ngx_array_t  *a, b;

/* create an array of strings with preallocated memory for 10 elements */
a = ngx_array_create(pool, 10, sizeof(ngx_str_t));

/* initialize string array for 10 elements */
ngx_array_init(&amp;b, pool, 10, sizeof(ngx_str_t));
</programlisting>

<para>
Adding elements to array are done with the following functions:
</para>

<para>
<list type="bullet">

<listitem>
<literal>ngx_array_push(a)</literal> adds one tail element and returns pointer
to it
</listitem>

<listitem>
<literal>ngx_array_push_n(a, n)</literal> adds <literal>n</literal> tail elements
and returns pointer to the first one
</listitem>

</list>
</para>

<para>
If currently allocated memory is not enough for new elements, a new memory for
elements is allocated and existing elements are copied to that memory.
The new memory block is normally twice as large, as the existing one.
</para>


<programlisting>
s = ngx_array_push(a);
ss = ngx_array_push_n(&amp;b, 3);
</programlisting>

</section>


<section name="List" id="list">

<para>
List in nginx is a sequence of arrays, optimized for inserting a potentially
large number of items. The list type is defined as follows:
</para>


<programlisting>
typedef struct {
    ngx_list_part_t  *last;
    ngx_list_part_t   part;
    size_t            size;
    ngx_uint_t        nalloc;
    ngx_pool_t       *pool;
} ngx_list_t;
</programlisting>

<para>
The actual items are stored in list parts, defined as follows:
</para>


<programlisting>
typedef struct ngx_list_part_s  ngx_list_part_t;

struct ngx_list_part_s {
    void             *elts;
    ngx_uint_t        nelts;
    ngx_list_part_t  *next;
};
</programlisting>

<para>
Initially, a list must be initialized by calling
<literal>ngx_list_init(list, pool, n, size)</literal> or created by calling
<literal>ngx_list_create(pool, n, size)</literal>.
Both functions receive the size of a single item and a number of items per list
part.
The <literal>ngx_list_push(list)</literal> function is used to add an item to the
list.  Iterating over the items is done by direct accessing the list fields, as
seen in the example:
</para>


<programlisting>
ngx_str_t        *v;
ngx_uint_t        i;
ngx_list_t       *list;
ngx_list_part_t  *part;

list = ngx_list_create(pool, 100, sizeof(ngx_str_t));
if (list == NULL) { /* error */ }

/* add items to the list */

v = ngx_list_push(list);
if (v == NULL) { /* error */ }
ngx_str_set(v, "foo");

v = ngx_list_push(list);
if (v == NULL) { /* error */ }
ngx_str_set(v, "bar");

/* iterate over the list */

part = &amp;list->part;
v = part->elts;

for (i = 0; /* void */; i++) {

    if (i >= part->nelts) {
        if (part->next == NULL) {
            break;
        }

        part = part->next;
        v = part->elts;
        i = 0;
    }

    ngx_do_smth(&amp;v[i]);
}
</programlisting>

<para>
The primary use for the list in nginx is HTTP input and output headers.
</para>

<para>
The list does not support item removal.
However, when needed, items can internally be marked as missing without actual
removing from the list.
For example, HTTP output headers which are stored as
<literal>ngx_table_elt_t</literal> objects, are marked as missing by setting
the <literal>hash</literal> field of <literal>ngx_table_elt_t</literal> to
zero. Such items are explicitly skipped, when iterating over the headers.
</para>

</section>


<section name="Queue" id="queue">

<para>
Queue in nginx is an intrusive doubly linked list, with each node defined as
follows:
</para>


<programlisting>
typedef struct ngx_queue_s  ngx_queue_t;

struct ngx_queue_s {
    ngx_queue_t  *prev;
    ngx_queue_t  *next;
};
</programlisting>

<para>
The head queue node is not linked with any data. Before using, the list head
should be initialized with <literal>ngx_queue_init(q)</literal> call.
Queues support the following operations:
</para>

<para>
<list type="bullet">

<listitem>
<literal>ngx_queue_insert_head(h, x)</literal>,
<literal>ngx_queue_insert_tail(h, x)</literal> — insert a new node
</listitem>

<listitem>
<literal>ngx_queue_remove(x)</literal> — remove a queue node
</listitem>

<listitem>
<literal>ngx_queue_split(h, q, n)</literal> — split a queue at a node,
queue tail is returned in a separate queue
</listitem>

<listitem>
<literal>ngx_queue_add(h, n)</literal> — add second queue to the first queue
</listitem>

<listitem>
<literal>ngx_queue_head(h)</literal>,
<literal>ngx_queue_last(h)</literal> — get first or last queue node
</listitem>

<listitem>
<literal>ngx_queue_sentinel(h)</literal>
- get a queue sentinel object to end iteration at
</listitem>

<listitem>
<literal>ngx_queue_data(q, type, link)</literal> — get reference to the beginning of a
queue node data structure, considering the queue field offset in it
</listitem>

</list>
</para>

<para>
Example:
</para>


<programlisting>
typedef struct {
    ngx_str_t    value;
    ngx_queue_t  queue;
} ngx_foo_t;

ngx_foo_t    *f;
ngx_queue_t   values;

ngx_queue_init(&amp;values);

f = ngx_palloc(pool, sizeof(ngx_foo_t));
if (f == NULL) { /* error */ }
ngx_str_set(&amp;f->value, "foo");

ngx_queue_insert_tail(&amp;values, f);

/* insert more nodes here */

for (q = ngx_queue_head(&amp;values);
     q != ngx_queue_sentinel(&amp;values);
     q = ngx_queue_next(q))
{
    f = ngx_queue_data(q, ngx_foo_t, queue);

    ngx_do_smth(&amp;f->value);
}
</programlisting>

</section>


<section name="Red-Black tree" id="red_black_tree">

<para>
The <path>src/core/ngx_rbtree.h</path> header file provides access to the
effective implementation of red-black trees.
</para>


<programlisting>
typedef struct {
    ngx_rbtree_t       rbtree;
    ngx_rbtree_node_t  sentinel;

    /* custom per-tree data here */
} my_tree_t;

typedef struct {
    ngx_rbtree_node_t  rbnode;

    /* custom per-node data */
    foo_t              val;
} my_node_t;
</programlisting>

<para>
To deal with a tree as a whole, you need two nodes: root and sentinel.
Typically, they are added to some custom structure, thus allowing to
organize your data into a tree which leaves contain a link to or embed
your data.
</para>

<para>
To initialize a tree:
</para>


<programlisting>
my_tree_t  root;

ngx_rbtree_init(&amp;root.rbtree, &amp;root.sentinel, insert_value_function);
</programlisting>

<para>
The <literal>insert_value_function</literal> is a function that is
responsible for traversing the tree and inserting new values into correct
place.
For example, the <literal>ngx_str_rbtree_insert_value</literal> functions is
designed to deal with <literal>ngx_str_t</literal> type.
</para>


<programlisting>
void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp,
                                 ngx_rbtree_node_t *node,
                                 ngx_rbtree_node_t *sentinel)
</programlisting>

<para>
Its arguments are pointers to a root node of an insertion, newly created node
to be added, and a tree sentinel.
</para>

<para>
The traversal is pretty straightforward and can be demonstrated with the
following lookup function pattern:
</para>


<programlisting>
my_node_t *
my_rbtree_lookup(ngx_rbtree_t *rbtree, foo_t *val, uint32_t hash)
{
    ngx_int_t           rc;
    my_node_t          *n;
    ngx_rbtree_node_t  *node, *sentinel;

    node = rbtree->root;
    sentinel = rbtree->sentinel;

    while (node != sentinel) {

        n = (my_node_t *) node;

        if (hash != node->key) {
            node = (hash &lt; node->key) ? node->left : node->right;
            continue;
        }

        rc = compare(val, node->val);

        if (rc &lt; 0) {
            node = node->left;
            continue;
        }

        if (rc > 0) {
            node = node->right;
            continue;
        }

        return n;
    }

    return NULL;
}
</programlisting>

<para>
The <literal>compare()</literal> is a classic comparator function returning
value less, equal or greater than zero. To speed up lookups and avoid comparing
user objects that can be big, integer hash field is used.
</para>

<para>
To add a node to a tree, allocate a new node, initialize it and call
<literal>ngx_rbtree_insert()</literal>:
</para>


<programlisting>
    my_node_t          *my_node;
    ngx_rbtree_node_t  *node;

    my_node = ngx_palloc(...);
    init_custom_data(&amp;my_node->val);

    node = &amp;my_node->rbnode;
    node->key = create_key(my_node->val);

    ngx_rbtree_insert(&amp;root->rbtree, node);
</programlisting>

<para>
to remove a node:
</para>


<programlisting>
ngx_rbtree_delete(&amp;root->rbtree, node);
</programlisting>

</section>

<section name="Hash" id="hash">

<para>
Hash table functions are declared in <path>src/core/ngx_hash.h</path>.
Exact and wildcard matching is supported.
The latter requires extra setup and is described in a separate section below.
</para>

<para>
To initialize a hash, one needs to know the number of elements in advance,
so that nginx can build the hash optimally.
Two parameters that need to be configured are <literal>max_size</literal>
and <literal>bucket_size</literal>.
The details of setting up these are provided in a separate
<link doc="../hash.xml">document</link>.
Usually, these two parameters are configurable by user.
Hash initialization settings are stored as the
<literal>ngx_hash_init_t</literal> type,
and the hash itself is <literal>ngx_hash_t</literal>:
<programlisting>
ngx_hash_t       foo_hash;
ngx_hash_init_t  hash;

hash.hash = &amp;foo_hash;
hash.key = ngx_hash_key;
hash.max_size = 512;
hash.bucket_size = ngx_align(64, ngx_cacheline_size);
hash.name = "foo_hash";
hash.pool = cf-&gt;pool;
hash.temp_pool = cf-&gt;temp_pool;
</programlisting>
The <literal>key</literal> is a pointer to a function that creates hash integer
key from a string.
Two generic functions are provided:
<literal>ngx_hash_key(data, len)</literal> and
<literal>ngx_hash_key_lc(data, len)</literal>.
The latter converts a string to lowercase and thus requires the passed string to
be writable.
If this is not true, <literal>NGX_HASH_READONLY_KEY</literal> flag
may be passed to the function, initializing array keys (see below).
</para>

<para>
The hash keys are stored in <literal>ngx_hash_keys_arrays_t</literal> and
are initialized with <literal>ngx_hash_keys_array_init(arr, type)</literal>:
<programlisting>
ngx_hash_keys_arrays_t  foo_keys;

foo_keys.pool = cf-&gt;pool;
foo_keys.temp_pool = cf-&gt;temp_pool;

ngx_hash_keys_array_init(&amp;foo_keys, NGX_HASH_SMALL);
</programlisting>
The second parameter can be either <literal>NGX_HASH_SMALL</literal> or
<literal>NGX_HASH_LARGE</literal> and controls the amount of preallocated
resources for the hash.
If you expect the hash to contain thousands elements,
use <literal>NGX_HASH_LARGE</literal>.
</para>

<para>
The <literal>ngx_hash_add_key(keys_array, key, value, flags)</literal>
function is used to insert keys into hash keys array;
<programlisting>
ngx_str_t k1 = ngx_string("key1");
ngx_str_t k2 = ngx_string("key2");

ngx_hash_add_key(&amp;foo_keys, &amp;k1, &amp;my_data_ptr_1, NGX_HASH_READONLY_KEY);
ngx_hash_add_key(&amp;foo_keys, &amp;k2, &amp;my_data_ptr_2, NGX_HASH_READONLY_KEY);
</programlisting>
</para>

<para>
Now, the hash table may be built using the call to
<literal>ngx_hash_init(hinit, key_names, nelts)</literal>:

<programlisting>
ngx_hash_init(&amp;hash, foo_keys.keys.elts, foo_keys.keys.nelts);
</programlisting>

This may fail, if <literal>max_size</literal> or <literal>bucket_size</literal>
parameters are not big enough.
When the hash is built, <literal>ngx_hash_find(hash, key, name, len)</literal>
function may be used to look up elements:
<programlisting>
my_data_t   *data;
ngx_uint_t   key;

key = ngx_hash_key(k1.data, k1.len);

data = ngx_hash_find(&amp;foo_hash, key, k1.data, k1.len);
if (data == NULL) {
    /* key not found */
}
</programlisting>

</para>

<section name="Wildcard matching" id="wildcard_matching">

<para>
To create a hash that works with wildcards,
<literal>ngx_hash_combined_t</literal> type is used.
It includes the hash type described above and has two additional keys arrays:
<literal>dns_wc_head</literal> and <literal>dns_wc_tail</literal>.
The initialization of basic properties is done similarly to a usual hash:
<programlisting>
ngx_hash_init_t      hash
ngx_hash_combined_t  foo_hash;

hash.hash = &amp;foo_hash.hash;
hash.key = ...;
</programlisting>
</para>

<para>
It is possible to add wildcard keys using the
<literal>NGX_HASH_WILDCARD_KEY</literal> flag:
<programlisting>
/* k1 = ".example.org"; */
/* k2 = "foo.*";        */
ngx_hash_add_key(&amp;foo_keys, &amp;k1, &amp;data1, NGX_HASH_WILDCARD_KEY);
ngx_hash_add_key(&amp;foo_keys, &amp;k2, &amp;data2, NGX_HASH_WILDCARD_KEY);
</programlisting>
The function recognizes wildcards and adds keys into corresponding arrays.
Please refer to the
<link doc="../http/ngx_http_map_module.xml" id="map"/> module
documentation for the description of the wildcard syntax and
matching algorithm.
</para>

<para>
Depending on the contents of added keys, you may need to initialize up to three
keys arrays: one for exact matching (described above), and two for matching
starting from head or tail of a string:
<programlisting>
if (foo_keys.dns_wc_head.nelts) {

    ngx_qsort(foo_keys.dns_wc_head.elts,
              (size_t) foo_keys.dns_wc_head.nelts,
              sizeof(ngx_hash_key_t),
              cmp_dns_wildcards);

    hash.hash = NULL;
    hash.temp_pool = pool;

    if (ngx_hash_wildcard_init(&amp;hash, foo_keys.dns_wc_head.elts,
                               foo_keys.dns_wc_head.nelts)
        != NGX_OK)
    {
        return NGX_ERROR;
    }

    foo_hash.wc_head = (ngx_hash_wildcard_t *) hash.hash;
}
</programlisting>
The keys array needs to be sorted, and initialization results must be added
to the combined hash.
The initialization of <literal>dns_wc_tail</literal> array is done similarly.
</para>

<para>
The lookup in a combined hash is handled by the
<literal>ngx_hash_find_combined(chash, key, name, len)</literal>:
<programlisting>
/* key = "bar.example.org"; — will match ".example.org" */
/* key = "foo.example.com"; — will match "foo.*"        */

hkey = ngx_hash_key(key.data, key.len);
res = ngx_hash_find_combined(&amp;foo_hash, hkey, key.data, key.len);
</programlisting>
</para>

</section>

</section>

</section>


<section name="Memory management" id="memory_management">


<section name="Heap" id="heap">

<para>
To allocate memory from system heap, the following functions are provided by
nginx:
</para>

<para>
<list type="bullet">

<listitem>
<literal>ngx_alloc(size, log)</literal> — allocate memory from system heap.
This is a wrapper around <literal>malloc()</literal> with logging support.
Allocation error and debugging information is logged to <literal>log</literal>
</listitem>

<listitem>
<literal>ngx_calloc(size, log)</literal> — same as
<literal>ngx_alloc()</literal>, but memory is filled with zeroes after
allocation
</listitem>

<listitem>
<literal>ngx_memalign(alignment, size, log)</literal> — allocate aligned memory
from system heap. This is a wrapper around <literal>posix_memalign()</literal>
on those platforms which provide it.
Otherwise implementation falls back to <literal>ngx_alloc()</literal> which
provides maximum alignment
</listitem>

<listitem>
<literal>ngx_free(p)</literal> — free allocated memory.
This is a wrapper around <literal>free()</literal>
</listitem>

</list>
</para>

</section>


<section name="Pool" id="pool">

<para>
Most nginx allocations are done in pools. Memory allocated in an nginx pool is
freed automatically when the pool in destroyed. This provides good
allocation performance and makes memory control easy.
</para>

<para>
A pool internally allocates objects in continuous blocks of memory. Once a
block is full, a new one is allocated and added to the pool memory
block list. When a large allocation is requested which does not fit into
a block, such allocation is forwarded to the system allocator and the
returned pointer is stored in the pool for further deallocation.
</para>

<para>
Nginx pool has the type <literal>ngx_pool_t</literal>.
The following operations are supported:
</para>

<para>
<list type="bullet">

<listitem>
<literal>ngx_create_pool(size, log)</literal> — create a pool with given
block size. The pool object returned is allocated in the pool as well.
</listitem>

<listitem>
<literal>ngx_destroy_pool(pool)</literal> — free all pool memory, including
the pool object itself.
</listitem>

<listitem>
<literal>ngx_palloc(pool, size)</literal> — allocate aligned memory from pool
</listitem>

<listitem>
<literal>ngx_pcalloc(pool, size)</literal> — allocated aligned memory
from pool and fill it with zeroes
</listitem>

<listitem>
<literal>ngx_pnalloc(pool, size)</literal> — allocate unaligned memory from pool.
Mostly used for allocating strings
</listitem>

<listitem>
<literal>ngx_pfree(pool, p)</literal> — free memory, previously allocated
in the pool.
Only allocations, forwarded to the system allocator, can be freed.
</listitem>

</list>
</para>

<programlisting>
u_char      *p;
ngx_str_t   *s;
ngx_pool_t  *pool;

pool = ngx_create_pool(1024, log);
if (pool == NULL) { /* error */ }

s = ngx_palloc(pool, sizeof(ngx_str_t));
if (s == NULL) { /* error */ }
ngx_str_set(s, "foo");

p = ngx_pnalloc(pool, 3);
if (p == NULL) { /* error */ }
ngx_memcpy(p, "foo", 3);
</programlisting>

<para>
Since chain links <literal>ngx_chain_t</literal> are actively used in nginx,
nginx pool provides a way to reuse them.
The <literal>chain</literal> field of <literal>ngx_pool_t</literal> keeps a
list of previously allocated links ready for reuse. For efficient allocation of
a chain link in a pool, the function
<literal>ngx_alloc_chain_link(pool)</literal> should be used.
This function looks up a free chain link in the pool list and only if it's
empty allocates a new one.  To free a link <literal>ngx_free_chain(pool, cl)</literal>
should be called.
</para>

<para>
Cleanup handlers can be registered in a pool.
Cleanup handler is a callback with an argument which is called when pool is
destroyed.
Pool is usually tied with a specific nginx object (like HTTP request) and
destroyed in the end of that object’s lifetime, releasing the object itself.
Registering a pool cleanup is a convenient way to release resources, close file
descriptors or make final adjustments to shared data, associated with the main
object.
</para>

<para>
A pool cleanup is registered by calling <literal>ngx_pool_cleanup_add(pool,
size)</literal> which returns <literal>ngx_pool_cleanup_t</literal> pointer to
be filled by the caller. The <literal>size</literal> argument allows allocating
context for the cleanup handler.
</para>


<programlisting>
ngx_pool_cleanup_t  *cln;

cln = ngx_pool_cleanup_add(pool, 0);
if (cln == NULL) { /* error */ }

cln->handler = ngx_my_cleanup;
cln->data = "foo";

...

static void
ngx_my_cleanup(void *data)
{
    u_char  *msg = data;

    ngx_do_smth(msg);
}
</programlisting>

</section>


<section name="Shared memory" id="shared_memory">

<para>
Shared memory is used by nginx to share common data between processes.
Function <literal>ngx_shared_memory_add(cf, name, size, tag)</literal> adds a
new shared memory entry <literal>ngx_shm_zone_t</literal> to the cycle.  The
function receives <literal>name</literal> and <literal>size</literal> of the
zone.
Each shared zone must have a unique name.
If a shared zone entry with the provided name exists, the old zone entry is
reused, if its tag value matches too.
Mismatched tag is considered an error.
Usually, the address of the module structure is passed as tag, making it
possible to reuse shared zones by name within one nginx module.
</para>

<para>
The shared memory entry structure <literal>ngx_shm_zone_t</literal> has the
following fields:
</para>

<para>
<list type="bullet">

<listitem>
<literal>init</literal> — initialization callback, called after shared zone is
mapped to actual memory
</listitem>

<listitem>
<literal>data</literal> — data context, used to pass arbitrary data to the
<literal>init</literal> callback
</listitem>

<listitem>
<literal>noreuse</literal> — flag, disabling shared zone reuse from the
old cycle
</listitem>

<listitem>
<literal>tag</literal> — shared zone tag
</listitem>

<listitem>
<literal>shm</literal> — platform-specific object of type
<literal>ngx_shm_t</literal>, having at least the following fields:
<list type="bullet">

<listitem>
<literal>addr</literal> — mapped shared memory address, initially NULL
</listitem>

<listitem>
<literal>size</literal> — shared memory size
</listitem>

<listitem>
<literal>name</literal> — shared memory name
</listitem>

<listitem>
<literal>log</literal> — shared memory log
</listitem>

<listitem>
<literal>exists</literal> — flag, showing that shared memory was inherited
from the master process (Windows-specific)
</listitem>

</list>
</listitem>

</list>
</para>

<para>
Shared zone entries are mapped to actual memory in
<literal>ngx_init_cycle()</literal> after configuration is parsed.
On POSIX systems, <literal>mmap()</literal> syscall is used to create shared
anonymous mapping.
On Windows, <literal>CreateFileMapping()/MapViewOfFileEx()</literal> pair is
used.
</para>

<para>
For allocating in shared memory, nginx provides slab pool
<literal>ngx_slab_pool_t</literal>.
In each nginx shared zone, a slab pool is automatically created for allocating
memory in that zone.
The pool is located in the beginning of the shared zone and can be accessed by
the expression <literal>(ngx_slab_pool_t *) shm_zone->shm.addr</literal>.
Allocation in shared zone is done by calling one of the functions
<literal>ngx_slab_alloc(pool, size)/ngx_slab_calloc(pool, size)</literal>.
Memory is freed by calling <literal>ngx_slab_free(pool, p)</literal>.
</para>

<para>
Slab pool divides all shared zone into pages.
Each page is used for allocating objects of the same size.
Only the sizes which are powers of 2, and not less than 8, are considered.
Other sizes are rounded up to one of these values.
For each page, a bitmask is kept, showing which blocks within that page are in
use and which are free for allocation.
For sizes greater than half-page (usually, 2048 bytes), allocation is done by
entire pages.
</para>

<para>
To protect data in shared memory from concurrent access, mutex is available in
the <literal>mutex</literal> field of <literal>ngx_slab_pool_t</literal>.
The mutex is used by the slab pool while allocating and freeing memory.
However, it can be used to protect any other user data structures,
allocated in the shared zone.
Locking is done by calling
<literal>ngx_shmtx_lock(&amp;shpool->mutex)</literal>, unlocking is done by
calling <literal>ngx_shmtx_unlock(&amp;shpool->mutex)</literal>.
</para>


<programlisting>
ngx_str_t        name;
ngx_foo_ctx_t   *ctx;
ngx_shm_zone_t  *shm_zone;

ngx_str_set(&amp;name, "foo");

/* allocate shared zone context */
ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t));
if (ctx == NULL) {
    /* error */
}

/* add an entry for 65k shared zone */
shm_zone = ngx_shared_memory_add(cf, &amp;name, 65536, &amp;ngx_foo_module);
if (shm_zone == NULL) {
    /* error */
}

/* register init callback and context */
shm_zone->init = ngx_foo_init_zone;
shm_zone->data = ctx;


...


static ngx_int_t
ngx_foo_init_zone(ngx_shm_zone_t *shm_zone, void *data)
{
    ngx_foo_ctx_t  *octx = data;

    size_t            len;
    ngx_foo_ctx_t    *ctx;
    ngx_slab_pool_t  *shpool;

    value = shm_zone->data;

    if (octx) {
        /* reusing a shared zone from old cycle */
        ctx->value = octx->value;
        return NGX_OK;
    }

    shpool = (ngx_slab_pool_t *) shm_zone->shm.addr;

    if (shm_zone->shm.exists) {
        /* initialize shared zone context in Windows nginx worker */
        ctx->value = shpool->data;
        return NGX_OK;
    }

    /* initialize shared zone */

    ctx->value = ngx_slab_alloc(shpool, sizeof(ngx_uint_t));
    if (ctx->value == NULL) {
        return NGX_ERROR;
    }

    shpool->data = ctx->value;

    return NGX_OK;
}
</programlisting>

</section>


</section>


<section name="Logging" id="logging">

<para>
For logging nginx code uses <literal>ngx_log_t</literal> objects.
Nginx logger provides support for several types of output:

<list type="bullet">

<listitem>
stderr — logging to standard error output
</listitem>

<listitem>
file — logging to file
</listitem>

<listitem>
syslog — logging to syslog
</listitem>

<listitem>
memory — logging to internal memory storage for development purposes.
The memory could be accessed later with debugger
</listitem>

</list>
</para>

<para>
A logger instance may actually be a chain of loggers, linked to each other with
the <literal>next</literal> field.
Each message is written to all loggers in chain.
</para>

<para>
Each logger has an error level which limits the messages written to that log.
The following error levels are supported by nginx:
</para>

<para>
<list type="bullet">

<listitem>
 <literal>NGX_LOG_EMERG</literal>
</listitem>

<listitem>
 <literal>NGX_LOG_ALERT</literal>
</listitem>

<listitem>
 <literal>NGX_LOG_CRIT</literal>
</listitem>

<listitem>
 <literal>NGX_LOG_ERR</literal>
</listitem>

<listitem>
 <literal>NGX_LOG_WARN</literal>
</listitem>

<listitem>
 <literal>NGX_LOG_NOTICE</literal>
</listitem>

<listitem>
 <literal>NGX_LOG_INFO</literal>
</listitem>

<listitem>
 <literal>NGX_LOG_DEBUG</literal>
</listitem>

</list>
</para>

<para>
For debug logging, debug mask is checked as well. The following debug masks
exist:
</para>

<para>
<list type="bullet">

<listitem>
 <literal>NGX_LOG_DEBUG_CORE</literal>
</listitem>

<listitem>
 <literal>NGX_LOG_DEBUG_ALLOC</literal>
</listitem>

<listitem>
 <literal>NGX_LOG_DEBUG_MUTEX</literal>
</listitem>

<listitem>
 <literal>NGX_LOG_DEBUG_EVENT</literal>
</listitem>

<listitem>
 <literal>NGX_LOG_DEBUG_HTTP</literal>
</listitem>

<listitem>
 <literal>NGX_LOG_DEBUG_MAIL</literal>
</listitem>

<listitem>
 <literal>NGX_LOG_DEBUG_STREAM</literal>
</listitem>

</list>
</para>

<para>
Normally, loggers are created by existing nginx code from
<literal>error_log</literal> directives and are available at nearly every stage
of processing in cycle, configuration, client connection and other objects.
</para>

<para>
Nginx provides the following logging macros:
</para>

<para>
<list type="bullet">

<listitem>
<literal>ngx_log_error(level, log, err, fmt, ...)</literal> — error logging
</listitem>

<listitem>
<literal>ngx_log_debug0(level, log, err, fmt)</literal>,
<literal>ngx_log_debug1(level, log, err, fmt, arg1)</literal> etc — debug
logging, up to 8 formatting arguments are supported
</listitem>

</list>
</para>

<para>
A log message is formatted in a buffer of size
<literal>NGX_MAX_ERROR_STR</literal> (currently, 2048 bytes) on stack.
The message is prepended with error level, process PID, connection id (stored
in <literal>log->connection</literal>) and system error text.
For non-debug messages <literal>log->handler</literal> is called as well to
prepend more specific information to the log message.
HTTP module sets <literal>ngx_http_log_error()</literal> function as log
handler to log client and server addresses, current action (stored in
<literal>log->action</literal>), client request line, server name etc.
</para>

<para>
Example:
</para>


<programlisting>
/* specify what is currently done */
log->action = "sending mp4 to client”;

/* error and debug log */
ngx_log_error(NGX_LOG_INFO, c->log, 0, "client prematurely
              closed connection”);

ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0,
               "mp4 start:%ui, length:%ui”, mp4->start, mp4->length);
</programlisting>

<para>
Logging result:
</para>


<programlisting>
2016/09/16 22:08:52 [info] 17445#0: *1 client prematurely closed connection while
sending mp4 to client, client: 127.0.0.1, server: , request: "GET /file.mp4 HTTP/1.1”
2016/09/16 23:28:33 [debug] 22140#0: *1 mp4 start:0, length:10000
</programlisting>

</section>


<section name="Cycle" id="cycle">

<para>
Cycle object keeps nginx runtime context, created from a specific
configuration.
The type of the cycle is <literal>ngx_cycle_t</literal>.
Upon configuration reload a new cycle is created from the new version of nginx
configuration.
The old cycle is usually deleted after a new one is successfully created.
Currently active cycle is held in the <literal>ngx_cycle</literal> global
variable and is inherited by newly started nginx workers.
</para>

<para>
A cycle is created by the function <literal>ngx_init_cycle()</literal>.
The function receives the old cycle as the argument.
It's used to locate the configuration file and inherit as much resources as
possible from the old cycle to keep nginx running smoothly.
When nginx starts, a fake cycle called “init cycle” is created and is then
replaced by a normal cycle, built from configuration.
</para>

<para>
Some members of the cycle:
</para>

<para>
<list type="bullet">

<listitem>
<literal>pool</literal> — cycle pool. Created for each new cycle
</listitem>

<listitem>
<literal>log</literal> — cycle log. Initially, this log is inherited from the
old cycle.
After reading configuration, this member is set to point to
<literal>new_log</literal>
</listitem>

<listitem>
<literal>new_log</literal> — cycle log, created by the configuration.
It's affected by the root scope <literal>error_log</literal> directive
</listitem>

<listitem>
<literal>connections</literal>, <literal>connections_n</literal> — per-worker
array of connections of type <literal>ngx_connection_t</literal>, created by
the event module while initializing each nginx worker.
The number of connections is set by the <literal>worker_connections</literal>
directive
</listitem>

<listitem>
<literal>free_connections</literal>,
<literal>free_connections_n</literal> — the and number of currently available
connections.
If no connections are available, nginx worker refuses to accept new clients
</listitem>

<listitem>
<literal>files</literal>, <literal>files_n</literal> — array for mapping file
descriptors to nginx connections.
This mapping is used by the event modules, having the
<literal>NGX_USE_FD_EVENT</literal> flag (currently, it's poll and devpoll)
</listitem>

<listitem>
<literal>conf_ctx</literal> — array of core module configurations.
The configurations are created and filled while reading nginx configuration
files
</listitem>

<listitem>
<literal>modules</literal>, <literal>modules_n</literal> — array of modules
<literal>ngx_module_t</literal>, both static and dynamic, loaded by current
configuration
</listitem>

<listitem>
<literal>listening</literal> — array of listening objects
<literal>ngx_listening_t</literal>.
Listening objects are normally added by the the <literal>listen</literal>
directive of different modules which call the
<literal>ngx_create_listening()</literal> function.
Based on listening objects, listen sockets are created by nginx
</listitem>

<listitem>
<literal>paths</literal> — array of paths <literal>ngx_path_t</literal>.
Paths are added by calling the function <literal>ngx_add_path()</literal> from
modules which are going to operate on certain directories.
These directories are created by nginx after reading configuration, if missing.
Moreover, two handlers can be added for each path:

<list type="bullet">

<listitem>
path loader — executed only once in 60 seconds after starting or reloading
nginx. Normally, reads the directory and stores data in nginx shared
memory. The handler is called from a dedicated nginx process “nginx
cache loader”
</listitem>

<listitem>
path manager — executed periodically. Normally, removes old files from the
directory and reflects these changes in nginx memory. The handler is
called from a dedicated nginx process “nginx cache manager”
</listitem>

</list>
</listitem>

<listitem>
<literal>open_files</literal> — list of <literal>ngx_open_file_t</literal>
objects.
An open file object is created by calling the function
<literal>ngx_conf_open_file()</literal>.
After reading configuration nginx opens all files from the
<literal>open_files</literal> list and stores file descriptors in the
<literal>fd</literal> field of each open file object.
The files are opened in append mode and created if missing.
The files from this list are reopened by nginx workers upon receiving the
reopen signal (usually it's <literal>USR1</literal>).
In this case the <literal>fd</literal> fields are changed to new descriptors.
The open files are currently used for logging
</listitem>

<listitem>
<literal>shared_memory</literal> — list of shared memory zones, each added by
calling the <literal>ngx_shared_memory_add()</literal> function.
Shared zones are mapped to the same address range in all nginx processes and
are used to share common data, for example HTTP cache in-memory tree
</listitem>

</list>
</para>

</section>

<section name="Buffer" id="buffer">

<para>
For input/output operations, nginx provides the buffer type
<literal>ngx_buf_t</literal>.
Normally, it's used to hold data to be written to a destination or read from a
source.
Buffer can reference data in memory and in file.
Technically it's possible that a buffer references both at the same time.
Memory for the buffer is allocated separately and is not related to the buffer
structure <literal>ngx_buf_t</literal>.
</para>

<para>
The structure <literal>ngx_buf_t</literal> has the following fields:
</para>

<para>
<list type="bullet">

<listitem>
<literal>start</literal>, <literal>end</literal> — the boundaries of memory
block, allocated for the buffer
</listitem>

<listitem>
<literal>pos</literal>, <literal>last</literal> — memory buffer boundaries,
normally a subrange of <literal>start</literal> .. <literal>end</literal>
</listitem>

<listitem>
<literal>file_pos</literal>, <literal>file_last</literal> — file buffer
boundaries, these are offsets from the beginning of the file
</listitem>

<listitem>
<literal>tag</literal> — unique value, used to distinguish buffers, created by
different nginx module, usually, for the purpose of buffer reuse
</listitem>

<listitem>
<literal>file</literal> — file object
</listitem>

<listitem>
<literal>temporary</literal> — flag, meaning that the buffer references
writable memory
</listitem>

<listitem>
<literal>memory</literal> — flag, meaning that the buffer references read-only
memory
</listitem>

<listitem>
<literal>in_file</literal> — flag, meaning that current buffer references data
in a file
</listitem>

<listitem>
<literal>flush</literal> — flag, meaning that all data prior to this buffer
should be flushed
</listitem>

<listitem>
<literal>recycled</literal> — flag, meaning that the buffer can be reused and
should be consumed as soon as possible
</listitem>

<listitem>
<literal>sync</literal> — flag, meaning that the buffer carries no data or
special signal like <literal>flush</literal> or <literal>last_buf</literal>.
Normally, such buffers are considered an error by nginx. This flags allows
skipping the error checks
</listitem>

<listitem>
<literal>last_buf</literal> — flag, meaning that current buffer is the last in
output
</listitem>

<listitem>
<literal>last_in_chain</literal> — flag, meaning that there's no more data
buffers in a (sub)request
</listitem>

<listitem>
<literal>shadow</literal> — reference to another buffer, related to the current
buffer. Usually current buffer uses data from the shadow buffer. Once current
buffer is consumed, the shadow buffer should normally also be marked as
consumed
</listitem>

<listitem>
<literal>last_shadow</literal> — flag, meaning that current buffer is the last
buffer, referencing a particular shadow buffer
</listitem>

<listitem>
<literal>temp_file</literal> — flag, meaning that the buffer is in a temporary
file
</listitem>

</list>
</para>

<para>
For input and output buffers are linked in chains.
Chain is a sequence of chain links <literal>ngx_chain_t</literal>, defined as
follows:
</para>


<programlisting>
typedef struct ngx_chain_s  ngx_chain_t;

struct ngx_chain_s {
    ngx_buf_t    *buf;
    ngx_chain_t  *next;
};
</programlisting>

<para>
Each chain link keeps a reference to its buffer and a reference to the next
chain link.
</para>

<para>
Example of using buffers and chains:
</para>


<programlisting>
ngx_chain_t *
ngx_get_my_chain(ngx_pool_t *pool)
{
    ngx_buf_t    *b;
    ngx_chain_t  *out, *cl, **ll;

    /* first buf */
    cl = ngx_alloc_chain_link(pool);
    if (cl == NULL) { /* error */ }

    b = ngx_calloc_buf(pool);
    if (b == NULL) { /* error */ }

    b->start = (u_char *) "foo";
    b->pos = b->start;
    b->end = b->start + 3;
    b->last = b->end;
    b->memory = 1; /* read-only memory */

    cl->buf = b;
    out = cl;
    ll = &amp;cl->next;

    /* second buf */
    cl = ngx_alloc_chain_link(pool);
    if (cl == NULL) { /* error */ }

    b = ngx_create_temp_buf(pool, 3);
    if (b == NULL) { /* error */ }

    b->last = ngx_cpymem(b->last, "foo", 3);

    cl->buf = b;
    cl->next = NULL;
    *ll = cl;

    return out;
}
</programlisting>

</section>


<section name="Networking" id="networking">


<!--
<section name="Network data types" id="network_data_types">

<para>
TBD: ngx_addr_t, ngx_url_t, ngx_socket_t, ngx_sockaddr_t, parse url, parse
address...
</para>

</section>
-->

<section name="Connection" id="connection">

<para>
Connection type <literal>ngx_connection_t</literal> is a wrapper around a
socket descriptor. Some of the structure fields are:
</para>

<para>
<list type="bullet">

<listitem>
<literal>fd</literal> — socket descriptor
</listitem>

<listitem>
<literal>data</literal> — arbitrary connection context.
Normally, a pointer to a higher level object, built on top of the connection,
like HTTP request or Stream session
</listitem>

<listitem>
<literal>read</literal>, <literal>write</literal> — read and write events for
the connection
</listitem>

<listitem>
<literal>recv</literal>, <literal>send</literal>,
<literal>recv_chain</literal>, <literal>send_chain</literal> — I/O operations
for the connection
</listitem>

<listitem>
<literal>pool</literal> — connection pool
</listitem>

<listitem>
<literal>log</literal> — connection log
</listitem>

<listitem>
<literal>sockaddr</literal>, <literal>socklen</literal>,
<literal>addr_text</literal> — remote socket address in binary and text forms
</listitem>

<listitem>
<literal>local_sockaddr</literal>, <literal>local_socklen</literal> — local
socket address in binary form.
Initially, these fields are empty.
Function <literal>ngx_connection_local_sockaddr()</literal> should be used to
get socket local address
</listitem>

<listitem>
<literal>proxy_protocol_addr</literal>, <literal>proxy_protocol_port</literal>
- PROXY protocol client address and port, if PROXY protocol is enabled for the
connection
</listitem>

<listitem>
<literal>ssl</literal> — nginx connection SSL context
</listitem>

<listitem>
<literal>reusable</literal> — flag, meaning, that the connection is at the
state, when it can be reused
</listitem>

<listitem>
<literal>close</literal> — flag, meaning, that the connection is being reused
and should be closed
</listitem>

</list>
</para>

<para>
An nginx connection can transparently encapsulate SSL layer.
In this case the connection <literal>ssl</literal> field holds a pointer to an
<literal>ngx_ssl_connection_t</literal> structure, keeping all SSL-related data
for the connection, including <literal>SSL_CTX</literal> and
<literal>SSL</literal>.
The handlers <literal>recv</literal>, <literal>send</literal>,
<literal>recv_chain</literal>, <literal>send_chain</literal> are set as well to
SSL functions.
</para>

<para>
The number of connections per nginx worker is limited by the
<literal>worker_connections</literal> value.
All connection structures are pre-created when a worker starts and stored in
the <literal>connections</literal> field of the cycle object.
To reach out for a connection structure, <literal>ngx_get_connection(s,
log)</literal> function is used.
The function receives a socket descriptor <literal>s</literal> which needs to
be wrapped in a connection structure.
</para>

<para>
Since the number of connections per worker is limited, nginx provides a
way to grab connections which are currently in use.
To enable or disable reuse of a connection, function
<literal>ngx_reusable_connection(c, reusable)</literal> is called.
Calling <literal>ngx_reusable_connection(c, 1)</literal> sets the
<literal>reuse</literal> flag of the connection structure and inserts the
connection in the <literal>reusable_connections_queue</literal> of the cycle.
Whenever <literal>ngx_get_connection()</literal> finds out there are no
available connections in the <literal>free_connections</literal> list of the
cycle, it calls <literal>ngx_drain_connections()</literal> to release a
specific number of reusable connections.
For each such connection, the <literal>close</literal> flag is set and its read
handler is called which is supposed to free the connection by calling
<literal>ngx_close_connection(c)</literal> and make it available for reuse.
To exit the state when a connection can be reused
<literal>ngx_reusable_connection(c, 0)</literal> is called.
An example of reusable connections in nginx is HTTP client connections which
are marked as reusable until some data is received from the client.
</para>

</section>


</section>


<section name="Events" id="events">


<section name="Event" id="event">

<para>
Event object <literal>ngx_event_t</literal> in nginx provides a way to be
notified of a specific event happening.
</para>

<para>
Some of the fields of the <literal>ngx_event_t</literal> are:
</para>

<para>
<list type="bullet">

<listitem>
<literal>data</literal> — arbitrary event context, used in event handler,
usually, a pointer to a connection, tied with the event
</listitem>

<listitem>
<literal>handler</literal> — callback function to be invoked when the event
happens
</listitem>

<listitem>
<literal>write</literal> — flag, meaning that this is the write event.
Used to distinguish between read and write events
</listitem>

<listitem>
<literal>active</literal> — flag, meaning that the event is registered for
receiving I/O notifications, normally from notification mechanisms like epoll,
kqueue, poll
</listitem>

<listitem>
<literal>ready</literal> — flag, meaning that the event has received an
I/O notification
</listitem>

<listitem>
<literal>delayed</literal> — flag, meaning that I/O is delayed due to rate
limiting
</listitem>

<listitem>
<literal>timer</literal> — Red-Black tree node for inserting the event into
the timer tree
</listitem>

<listitem>
<literal>timer_set</literal> — flag, meaning that the event timer is set,
but not yet expired
</listitem>

<listitem>
<literal>timedout</literal> — flag, meaning that the event timer has expired
</listitem>

<listitem>
<literal>eof</literal> — read event flag, meaning that the eof has happened
while reading data
</listitem>

<listitem>
<literal>pending_eof</literal> — flag, meaning that the eof is pending on the
socket, even though there may be some data available before it.
The flag is delivered via <literal>EPOLLRDHUP</literal> epoll event or
<literal>EV_EOF</literal> kqueue flag
</listitem>

<listitem>
<literal>error</literal> — flag, meaning that an error has happened while
reading (for read event) or writing (for write event)
</listitem>

<listitem>
<literal>cancelable</literal> — timer event flag, meaning that the event
handler should be called while performing nginx worker graceful shutdown, event
though event timeout has not yet expired.  The flag provides a way to finalize
certain activities, for example, flush log files
</listitem>

<listitem>
<literal>posted</literal> — flag, meaning that the event is posted to queue
</listitem>

<listitem>
<literal>queue</literal> — queue node for posting the event to a queue
</listitem>

</list>
</para>

</section>


<section name="I/O events" id="i_o_events">

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

</section>


<section name="Timer events" id="timer_events">

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

</section>


<section name="Posted events" id="posted_events">

<para>
An event can be posted which means that its handler will be called at some
point later within the current event loop iteration.
Posting events is a good practice for simplifying code and escaping stack
overflows.
Posted events are held in a post queue.
The macro <literal>ngx_post_event(ev, q)</literal> posts the event
<literal>ev</literal> to the post queue <literal>q</literal>.
Macro <literal>ngx_delete_posted_event(ev)</literal> deletes the event
<literal>ev</literal> from whatever queue it's currently posted.
Normally, events are posted to the <literal>ngx_posted_events</literal> queue.
This queue is processed late in the event loop — after all I/O and timer
events are already handled.
The function <literal>ngx_event_process_posted()</literal> is called to process
an event queue.
This function calls event handlers until the queue is not empty.  This means
that a posted event handler can post more events to be processed within the
current event loop iteration.
</para>

<para>
Example:
</para>


<programlisting>
void
ngx_my_connection_read(ngx_connection_t *c)
{
    ngx_event_t  *rev;

    rev = c->read;

    ngx_add_timer(rev, 1000);

    rev->handler = ngx_my_read_handler;

    ngx_my_read(rev);
}


void
ngx_my_read_handler(ngx_event_t *rev)
{
    ssize_t            n;
    ngx_connection_t  *c;
    u_char             buf[256];

    if (rev->timedout) { /* timeout expired */ }

    c = rev->data;

    while (rev->ready) {
        n = c->recv(c, buf, sizeof(buf));

        if (n == NGX_AGAIN) {
            break;
        }

        if (n == NGX_ERROR) { /* error */ }

        /* process buf */
    }

    if (ngx_handle_read_event(rev, 0) != NGX_OK) { /* error */ }
}
</programlisting>

</section>


<section name="Event loop" id="event_loop">

<para>
All nginx processes which do I/O, have an event loop.
The only type of process which does not have I/O, is nginx master process which
spends most of its time in <literal>sigsuspend()</literal> call waiting for
signals to arrive.
Event loop is implemented in <literal>ngx_process_events_and_timers()</literal>
function.
This function is called repeatedly until the process exits.
It has the following stages:
</para>

<para>
<list type="bullet">

<listitem>
find nearest timeout by calling <literal>ngx_event_find_timer()</literal>.
This function finds the leftmost timer tree node and returns the number of
milliseconds until that node expires
</listitem>

<listitem>
process I/O events by calling a handler, specific to event notification
mechanism, chosen by nginx configuration.
This handler waits for at least one I/O event to happen, but no longer, than
the nearest timeout.
For each read or write event which has happened, the <literal>ready</literal>
flag is set and its handler is called.
For Linux, normally, the <literal>ngx_epoll_process_events()</literal> handler
is used which calls <literal>epoll_wait()</literal> to wait for I/O events
</listitem>

<listitem>
expire timers by calling <literal>ngx_event_expire_timers()</literal>.
The timer tree is iterated from the leftmost element to the right until a not
yet expired timeout is found.
For each expired node the <literal>timedout</literal> event flag is set,
<literal>timer_set</literal> flag is reset, and the event handler is called
</listitem>

<listitem>
process posted events by calling <literal>ngx_event_process_posted()</literal>.
The function repeatedly removes the first element from the posted events
queue and calls its handler until the queue gets empty
</listitem>

</list>
</para>

<para>
All nginx processes handle signals as well.
Signal handlers only set global variables which are checked after the
<literal>ngx_process_events_and_timers()</literal> call.
</para>

</section>


</section>


<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>
global variable:
</para>

<list type="bullet">

<listitem>

<para>
<literal>NGX_PROCESS_MASTER</literal> — the master process runs the
<literal>ngx_master_process_cycle()</literal> function.
Master process does not have any I/O and responds only to signals.
It reads configuration, creates cycles, starts and controls child processes
</para>


</listitem>

<listitem>

<para>
<literal>NGX_PROCESS_WORKER</literal> — the worker process runs the
<literal>ngx_worker_process_cycle()</literal> function.
Worker processes are started by master and handle client connections.
They also respond to signals and channel commands, sent from master
</para>


</listitem>

<listitem>

<para>
<literal>NGX_PROCESS_SINGLE</literal> — single process is the only type
of processes which exist in the <literal>master_process off</literal> mode.
The cycle function for this process is
<literal>ngx_single_process_cycle()</literal>.
This process creates cycles and handles client connections
</para>


</listitem>

<listitem>

<para>
<literal>NGX_PROCESS_HELPER</literal> — currently, there are two types of
helper processes: cache manager and cache loader.
Both of them share the same cycle function
<literal>ngx_cache_manager_process_cycle()</literal>.
</para>


</listitem>

</list>

<para>
All nginx processes handle the following signals:
</para>

<list type="bullet">

<listitem>

<para>
<literal>NGX_SHUTDOWN_SIGNAL</literal> (<literal>SIGQUIT</literal>) — graceful
shutdown.
Upon receiving this signal master process sends shutdown signal to all child
processes.
When no child processes are left, master destroys cycle pool and exits.
A worker process which received this signal, closes all listening sockets and
waits until timeout tree becomes empty, then destroys cycle pool and exits.
A cache manager process exits right after receiving this signal.
The variable <literal>ngx_quit</literal> is set to one after receiving this
signal and immediately reset after being processed.
The variable <literal>ngx_exiting</literal> is set to one when worker process
is in shutdown state
</para>


</listitem>

<listitem>

<para>
<literal>NGX_TERMINATE_SIGNAL</literal> (<literal>SIGTERM</literal>) -
terminate.
Upon receiving this signal master process sends terminate signal to all child
processes.
If child processes do not exit in 1 second, they are killed with the
<literal>SIGKILL</literal> signal.
When no child processes are left, master process destroys cycle pool and exits.
A worker or cache manager process which received this signal destroys cycle
pool and exits.
The variable <literal>ngx_terminate</literal> is set to one after receiving
this signal
</para>


</listitem>

<listitem>

<para>
<literal>NGX_NOACCEPT_SIGNAL</literal> (<literal>SIGWINCH</literal>)
- gracefully shut down worker processes
</para>


</listitem>

<listitem>

<para>
<literal>NGX_RECONFIGURE_SIGNAL</literal> (<literal>SIGHUP</literal>) -
reconfigure.
Upon receiving this signal master process creates a new cycle from
configuration file.
If the new cycle was created successfully, the old cycle is deleted and new
child processes are started.
Meanwhile, the old processes receive the shutdown signal.
In single-process mode, nginx creates a new cycle as well, but keeps the old
one until all clients, tied to the old cycle, are gone.
Worker and helper processes ignore this signal
</para>


</listitem>

<listitem>

<para>
<literal>NGX_REOPEN_SIGNAL</literal> (<literal>SIGUSR1</literal>) — reopen
files.
Master process passes this signal to workers.
Worker processes reopen all <literal>open_files</literal> from the cycle
</para>


</listitem>

<listitem>

<para>
<literal>NGX_CHANGEBIN_SIGNAL</literal> (<literal>SIGUSR2</literal>) — change
nginx binary.
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
text format, where descriptor numbers separated with semicolons.
A new nginx instance reads that variable and adds the sockets to its init
cycle.
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
helpers with the standard <literal>kill()</literal> syscall.
Instead, nginx uses inter-process channels which allow sending messages between
all nginx processes.
Currently, however, messages are only sent from master to its children.
Those messages carry the same 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="Modules" id="Modules">

<section name="Adding new modules" id="adding_new_modules">
<para>
The standalone nginx module resides in a separate directory that contains
at least two files:
<literal>config</literal> and a file with the module source.
The first file contains all information needed for nginx to 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
following variables:
<list type="bullet">

<listitem>
<literal>ngx_module_type</literal> — the type of module to build.
Possible options 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>
</listitem>

<listitem>
<literal>ngx_module_name</literal> — the name of the module.
A whitespace separated values list is accepted and may be used to build
multiple modules from a single set of source files.
The first name indicates the name of the output binary for a dynamic module.
The names in this list should match the names used in the module.
</listitem>

<listitem>
<literal>ngx_addon_name</literal> — supplies the name of the module in the
console output text of the configure script.
</listitem>

<listitem>
<literal>ngx_module_srcs</literal> — a whitespace separated list of source
files used to compile the module.
The $ngx_addon_dir variable can be used as a placeholder for the path of the
module source.
</listitem>

<listitem>
<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.
</listitem>

<listitem>
<literal>ngx_module_libs</literal> — a list of libraries to link with the
module.
For example, libpthread would be linked using
<literal>ngx_module_libs=-lpthread</literal>.
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>
</listitem>

<listitem>
<literal>ngx_module_link</literal> — 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
linking type.
</listitem>

<listitem>
<literal>ngx_module_order</literal> — sets the load order for the module which
is useful for <literal>HTTP_FILTER</literal> and
<literal>HTTP_AUX_FILTER</literal> module types.
The order is stored in a reverse list.

<para>
The <literal>ngx_http_copy_filter_module</literal> is near the bottom of the
list so is one of the first to be executed.
This reads the data for other filters.
Near the top of the list is <literal>ngx_http_write_filter_module</literal>
which writes the data out and is one of the last to be executed.
</para>

<para>
The format for this option is typically the current module’s name followed by
a whitespace separated list of modules to insert before, and therefore execute
after.
The module will be inserted before the last module in the list that is found
to be currently loaded.
</para>

<para>
By default for filter modules this is set to
“<literal>ngx_http_copy_filter</literal>” which will insert the module before
the copy filter in the list and therefore will execute after the copy filter.
For other module types the default is empty.
</para>

</listitem>

</list>

A module can be added to nginx by means of the configure script using
<literal>--add-module=/path/to/module</literal> for static compilation and
<literal>--add-dynamic-module=/path/to/module</literal> for dynamic compilation.
</para>

</section>


<section name="Core modules" id="core_modules">

<para>
Modules are building blocks of nginx, and most of its functionality is
implemented as modules.
The module source file must contain a global variable of
<literal>ngx_module_t</literal> type which is defined as follows:
<programlisting>
struct ngx_module_s {

    /* private part is omitted */

    void                 *ctx;
    ngx_command_t        *commands;
    ngx_uint_t            type;

    ngx_int_t           (*init_master)(ngx_log_t *log);

    ngx_int_t           (*init_module)(ngx_cycle_t *cycle);

    ngx_int_t           (*init_process)(ngx_cycle_t *cycle);
    ngx_int_t           (*init_thread)(ngx_cycle_t *cycle);
    void                (*exit_thread)(ngx_cycle_t *cycle);
    void                (*exit_process)(ngx_cycle_t *cycle);

    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
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
<literal>commands</literal> array, and may 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
</listitem>

<listitem>
The <literal>init_module</literal> handler is called in the context of
the master process after the configuration is parsed successfully
</listitem>

<listitem>
The master process creates worker process(es) and
<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>

<listitem>
The master process calls the <literal>exit_master</literal> handler before
exiting.
</listitem>

</list>

<note>
<literal>init_module</literal> handler may be called multiple times
in the master process if the configuration reload is requested.
</note>

The <literal>init_master</literal>, <literal>init_thread</literal> and
<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
API and <literal>init_master</literal> handler looks unnecessary.
</para>

<para>
The module <literal>type</literal> defines what exactly is stored in the
<literal>ctx</literal> field.
There are several types of modules:
<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
on top of it and provide more convenient way to deal with corresponding
problem domains, like handling events or http requests.
</para>

<para>
The examples of core modules are <literal>ngx_core_module</literal>,
<literal>ngx_errlog_module</literal>, <literal>ngx_regex_module</literal>,
<literal>ngx_thread_pool_module</literal>,
<literal>ngx_openssl_module</literal>
modules and, of course, http, stream, mail and event modules itself.
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
convenience, <literal>create_conf</literal> and <literal>init_conf</literal>
are pointers to functions that create and initialize module configuration
correspondingly.
For core modules, nginx will call <literal>create_conf</literal> before parsing
a new configuration and <literal>init_conf</literal> after all configuration
was 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
perform sanity checks and complete initialization.
</para>

<para>
For example, the simplistic <literal>ngx_foo_module</literal> can look like
this:
<programlisting>
/*
 * Copyright (C) Author.
 */


#include &lt;ngx_config.h&gt;
#include &lt;ngx_core.h&gt;


typedef struct {
    ngx_flag_t  enable;
} ngx_foo_conf_t;


static void *ngx_foo_create_conf(ngx_cycle_t *cycle);
static char *ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf);

static char *ngx_foo_enable(ngx_conf_t *cf, void *post, void *data);
static ngx_conf_post_t  ngx_foo_enable_post = { ngx_foo_enable };


static ngx_command_t  ngx_foo_commands[] = {

    { ngx_string("foo_enabled"),
      NGX_MAIN_CONF|NGX_DIRECT_CONF|NGX_CONF_FLAG,
      ngx_conf_set_flag_slot,
      0,
      offsetof(ngx_foo_conf_t, enable),
      &amp;ngx_foo_enable_post },

      ngx_null_command
};


static ngx_core_module_t  ngx_foo_module_ctx = {
    ngx_string("foo"),
    ngx_foo_create_conf,
    ngx_foo_init_conf
};


ngx_module_t  ngx_foo_module = {
    NGX_MODULE_V1,
    &amp;ngx_foo_module_ctx,                   /* module context */
    ngx_foo_commands,                      /* module directives */
    NGX_CORE_MODULE,                       /* module type */
    NULL,                                  /* init master */
    NULL,                                  /* init module */
    NULL,                                  /* init process */
    NULL,                                  /* init thread */
    NULL,                                  /* exit thread */
    NULL,                                  /* exit process */
    NULL,                                  /* exit master */
    NGX_MODULE_V1_PADDING
};


static void *
ngx_foo_create_conf(ngx_cycle_t *cycle)
{
    ngx_foo_conf_t  *fcf;

    fcf = ngx_pcalloc(cycle->pool, sizeof(ngx_foo_conf_t));
    if (fcf == NULL) {
        return NULL;
    }

    fcf->enable = NGX_CONF_UNSET;

    return fcf;
}


static char *
ngx_foo_init_conf(ngx_cycle_t *cycle, void *conf)
{
    ngx_foo_conf_t *fcf = conf;

    ngx_conf_init_value(fcf->enable, 0);

    return NGX_CONF_OK;
}


static char *
ngx_foo_enable(ngx_conf_t *cf, void *post, void *data)
{
    ngx_flag_t  *fp = data;

    if (*fp == 0) {
        return NGX_CONF_OK;
    }

    ngx_log_error(NGX_LOG_NOTICE, cf->log, 0, "Foo Module is enabled");

    return NGX_CONF_OK;
}
</programlisting>
</para>

</section>


<section name="Configuration directives" id="config_directives">

<para>
The <literal>ngx_command_t</literal> describes single configuration directive.
Each module, supporting configuration, provides an array of such specifications
that describe how to process arguments and what handlers to call:
<programlisting>
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
“<literal>ngx_null_command</literal>”.
The <literal>name</literal> is the literal name of a directive, as it appears
in configuration file, for example “<literal>worker_processes</literal>” or
“<literal>listen</literal>”.
The <literal>type</literal> is a bitfield that controls number of arguments,
command type and other properties using corresponding flags.
Arguments flags:

<list type="bullet">

<listitem>
<literal>NGX_CONF_NOARGS</literal> — directive without arguments
</listitem>

<listitem><literal>NGX_CONF_1MORE</literal> — one required argument</listitem>

<listitem><literal>NGX_CONF_2MORE</literal> — two required arguments</listitem>

<listitem>
<literal>NGX_CONF_TAKE1..7</literal> — exactly 1..7 arguments
</listitem>

<listitem>
<literal>NGX_CONF_TAKE12, 13, 23, 123, 1234</literal> — one or two arguments,
or other combinations
</listitem>

</list>

Directive types:

<list type="bullet">

<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
to handle contents inside.
</listitem>

<listitem>
<literal>NGX_CONF_FLAG</literal> — the directive value is a flag, a boolean
value represented by “<literal>on</literal>” or “<literal>off</literal>”
strings.
</listitem>
</list>

Context of a directive defines where in the configuration it may appear
and how to access module context to store corresponding values:
<list type="bullet">

<listitem>
<literal>NGX_MAIN_CONF</literal> — top level configuration
</listitem>

<listitem>
<literal>NGX_HTTP_MAIN_CONF</literal> — in the http block
</listitem>

<listitem>
<literal>NGX_HTTP_SRV_CONF</literal> — in the http server block
</listitem>

<listitem>
<literal>NGX_HTTP_LOC_CONF</literal> — in the http location
</listitem>

<listitem>
<literal>NGX_HTTP_UPS_CONF</literal> — in the http upstream block
</listitem>

<listitem>
<literal>NGX_HTTP_SIF_CONF</literal> — in the http server “if”
</listitem>

<listitem>
<literal>NGX_HTTP_LIF_CONF</literal> — in the http location “if”
</listitem>

<listitem>
<literal>NGX_HTTP_LMT_CONF</literal> — in the http “limit_except”
</listitem>

<listitem>
<literal>NGX_STREAM_MAIN_CONF</literal> — in the stream block
</listitem>

<listitem>
<literal>NGX_STREAM_SRV_CONF</literal> — in the stream server block
</listitem>

<listitem>
<literal>NGX_STREAM_UPS_CONF</literal> — in the stream upstream block
</listitem>

<listitem>
<literal>NGX_MAIL_MAIN_CONF</literal> — in the the mail block
</listitem>

<listitem>
<literal>NGX_MAIL_SRV_CONF</literal> — in the mail server block
</listitem>

<listitem>
<literal>NGX_EVENT_CONF</literal> — in the event block
</listitem>

<listitem>
<literal>NGX_DIRECT_CONF</literal> — used by modules that don't
create a hierarchy of contexts and store module configuration directly in ctx
</listitem>
</list>
The configuration parser uses this 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
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.
Nginx offers a convenient set of functions that perform common conversions:

<list type="bullet">

<listitem>
<literal>ngx_conf_set_flag_slot</literal> — converts literal
“<literal>on</literal>” or “<literal>off</literal>” strings into
<literal>ngx_flag_t</literal> type with values 1 or 0
</listitem>

<listitem>
<literal>ngx_conf_set_str_slot</literal> — stores string as a value of the
<literal>ngx_str_t</literal> type
</listitem>

<listitem>
<literal>ngx_conf_set_str_array_slot</literal> — appends
<literal>ngx_array_t</literal> of <literal>ngx_str_t</literal> with a new value.
The array is created if not yet exists
</listitem>

<listitem>
<literal>ngx_conf_set_keyval_slot</literal> — appends
<literal>ngx_array_t</literal> of <literal>ngx_keyval_t</literal> with
a new value, where key is the first string and value is second.
The array is created if not yet exists
</listitem>

<listitem>
<literal>ngx_conf_set_num_slot</literal> — converts directive argument
to a <literal>ngx_int_t</literal> value
</listitem>

<listitem>
<literal>ngx_conf_set_size_slot</literal> — converts
<link doc="../syntax.xml">size</link> to <literal>size_t</literal> value
in bytes
</listitem>

<listitem>
<literal>ngx_conf_set_off_slot</literal> — converts
<link doc="../syntax.xml">offset</link> to <literal>off_t</literal> value
in bytes
</listitem>

<listitem>
<literal>ngx_conf_set_msec_slot</literal> — converts
<link doc="../syntax.xml">time</link> to <literal>ngx_msec_t</literal> value
in milliseconds
</listitem>

<listitem>
<literal>ngx_conf_set_sec_slot</literal> — converts
<link doc="../syntax.xml">time</link> to <literal>time_t</literal> value
in seconds
</listitem>

<listitem>
<literal>ngx_conf_set_bufs_slot</literal> — converts two arguments
into <literal>ngx_bufs_t</literal> that holds <literal>ngx_int_t</literal>
number and <link doc="../syntax.xml">size</link> of buffers
</listitem>

<listitem>
<literal>ngx_conf_set_enum_slot</literal> — converts argument
into <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
integer values
</listitem>

<listitem>
<literal>ngx_conf_set_bitmask_slot</literal> — arguments are converted to
<literal>ngx_uint_t</literal> value and OR'ed with the resulting value,
forming a bitmask.
The null-terminated array of <literal>ngx_conf_bitmask_t</literal> passed in
the <literal>post</literal> field defines acceptable strings and corresponding
mask values
</listitem>

<listitem>
<literal>set_path_slot</literal> — converts arguments to
<literal>ngx_path_t</literal> type and performs all required initializations.
See the
<link doc="../http/ngx_http_proxy_module.xml" id="proxy_temp_path">proxy_temp_path</link>
directive description for details
</listitem>

<listitem>
<literal>set_access_slot</literal> — converts arguments to file permissions
mask.
See the
<link doc="../http/ngx_http_proxy_module.xml" id="proxy_store_access">proxy_store_access</link>
directive description for details
</listitem>

</list>

</para>

<para>
The <literal>conf</literal> field defines which context is used to store
the value of the directive, or zero if contexts are not used.
Only simple core modules use configuration without context and set
<literal>NGX_DIRECT_CONF</literal> flag.
In real life, such modules like http or stream require more sophisticated
configuration that can be applied per-server or per-location, or even more
precisely, in the context of the “<literal>if</literal>” directive or
some limit.
In this modules, configuration structure is more complex.
Please refer to corresponding modules description to understand how
they manage their configuration.

<list type="bullet">
<listitem>
<literal>NGX_HTTP_MAIN_CONF_OFFSET</literal> — http block configuration
</listitem>

<listitem>
<literal>NGX_HTTP_SRV_CONF_OFFSET</literal> — http server configuration
</listitem>

<listitem>
<literal>NGX_HTTP_LOC_CONF_OFFSET</literal> — http location configuration
</listitem>

<listitem>
<literal>NGX_STREAM_MAIN_CONF_OFFSET</literal> — stream block configuration
</listitem>

<listitem>
<literal>NGX_STREAM_SRV_CONF_OFFSET</literal> — stream server configuration
</listitem>

<listitem>
<literal>NGX_MAIL_MAIN_CONF_OFFSET</literal> — mail block configuration
</listitem>

<listitem>
<literal>NGX_MAIL_SRV_CONF_OFFSET</literal> — mail server configuration
</listitem>

</list>

</para>

<para>
The <literal>offset</literal> defines an offset of a field in a module
configuration structure that holds values of this particular directive.
The typical use is to employ <literal>offsetof()</literal> macro.
</para>

<para>
The <literal>post</literal> is a twofold field: it may be used to define
a handler to be called after main handler completed or to pass additional
data to the main handler.
In the first case, <literal>ngx_conf_post_t</literal> structure needs to
be initialized with a pointer to 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,
converted from arguments by the main handler with the appropriate type.
</para>

</section>

</section>


<section name="HTTP" id="http">


<section name="Connection" id="http_connection">

<para>
Each client HTTP 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.
The object wraps 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>
</listitem>

<listitem>
<literal>ngx_http_init_connection()</literal> performs early initialization of
an 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
<literal>data</literal> field.
Later it will be substituted with an HTTP request object.
PROXY protocol parser and SSL handshake are started at this stage as well
</listitem>

<listitem>
<literal>ngx_http_wait_request_handler()</literal> is a read event handler, that
is called when data is available in 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
</listitem>

<listitem>
<literal>ngx_http_process_request_line()</literal> is a read event handler,
which 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 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.
If the initial size is not enough, a bigger buffer is allocated, whose size is
set by the <literal>large_client_header_buffers</literal> directive
</listitem>

<listitem>
<literal>ngx_http_process_request_headers()</literal> is a read event handler,
which is set after <literal>ngx_http_process_request_line()</literal> to read
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
chain.
The response in not necessarily sent to the client at this phase.
It may remain buffered and will 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
</listitem>

<listitem>
<literal>ngx_http_finalize_connection()</literal> is called when the response is
completely sent to the client and the request can be destroyed.
If client connection keepalive feature is enabled,
<literal>ngx_http_set_keepalive()</literal> is called, which destroys 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
</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:
</para>

<list type="bullet">

<listitem>

<para>
<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 -
one main request and its subrequests.
After a request is deleted, a new request may 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
connection.
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
output
</para>

</listitem>

<listitem>

<para>
<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>module</literal>'s context
</listitem>

<listitem>
<literal>ngx_http_set_ctx(r, c, module)</literal> — sets <literal>c</literal>
as <literal>module</literal>'s context
</listitem>

</list>

</listitem>

<listitem>
<literal>main_conf, srv_conf, loc_conf</literal> — arrays of current request
configurations.
Configurations are stored at 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.
Normally, an HTTP connection has <literal>ngx_http_request_handler()</literal>
set as both read and write event handlers.
This function calls <literal>read_event_handler</literal> and
<literal>write_event_handler</literal> handlers of the currently active request
</listitem>

<listitem>
<literal>cache</literal> — request cache object for caching upstream response
</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.
The request object itself is allocated in this pool.
For allocations which should be available throughout the client connection's
lifetime, <literal>ngx_connection_t</literal>'s pool should be used instead
</listitem>

<listitem>
<literal>header_in</literal> — buffer where client HTTP request header in read
</listitem>

<listitem>
<literal>headers_in, 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.
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
</listitem>

<listitem>
<literal>request_body</literal> — client request body object
</listitem>

<listitem>
<literal>start_sec, start_msec</literal> — time point when the request was
created.
Used for tracking request duration
</listitem>

<listitem>
<literal>method, method_name</literal> — numeric and textual representation of
client HTTP request method.
Numeric values for methods are defined in
<literal>src/http/ngx_http_request.h</literal> with macros
<literal>NGX_HTTP_GET, NGX_HTTP_HEAD, NGX_HTTP_POST</literal> etc
</listitem>

<listitem>
<literal>http_protocol, http_version, http_major, http_minor</literal> -
client HTTP protocol version in its original textual form (“HTTP/1.0”,
“HTTP/1.1” etc), numeric form (<literal>NGX_HTTP_VERSION_10</literal>,
<literal>NGX_HTTP_VERSION_11</literal> etc) and separate major and minor
versions
</listitem>

<listitem>
<literal>request_line, unparsed_uri</literal> — client original request line
and URI
</listitem>

<listitem>
<literal>uri, args, exten</literal> — current request URI, arguments and file
extention.
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
redirects
</listitem>

<listitem>
<literal>main</literal> — pointer to a main request object.
This object is created to process client HTTP request, as opposed to
subrequests, created to perform a specific sub-task within the main request
</listitem>

<listitem>
<literal>parent</literal> — pointer to a parent request of a subrequest
</listitem>

<listitem>
<literal>postponed</literal> — list of output buffers and subrequests in the
order they are sent and created.
The list is used by the postpone filter to provide consistent request output,
when parts of it are created by subrequests
</listitem>

<listitem>
<literal>post_subrequest</literal> — pointer to a handler with context to be
called when a subrequest gets finalized.
Unused for main requests
</listitem>

<listitem>

<para>
<literal>posted_requests</literal> — list of requests to be started or
resumed.
Starting or resuming 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.
This function should be called in all event handlers, which can lead to new
posted requests.
Normally, it's called always after invoking a request's read or write handler
</para>

</listitem>

<listitem>
<literal>phase_handler</literal> — index of current request phase
</listitem>

<listitem>
<literal>ncaptures, captures, 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
happen: map lookup, server lookup by SNI or HTTP Host, rewrite, proxy_redirect
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_data</literal> holds a string, against which the regex was
matched and which should be used to extract captures.
After each new regex match request captures are reset to hold new values
</listitem>

<listitem>
<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>
should be called.
Creation of a subrequest or running request body read process increase the
counter
</listitem>

<listitem>
<literal>subrequests</literal> — current subrequest nesting level.
Each subrequest gets the nesting level of its parent decreased by one.
Once the value reaches zero an error is generated.
The value for the main request is defined by the
<literal>NGX_HTTP_MAX_SUBREQUESTS</literal> constant
</listitem>

<listitem>
<literal>uri_changes</literal> — number of URI changes left 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.
In the latter case an error is generated.
The actions considered as URI changes are rewrites and internal redirects to
normal or named locations
</listitem>

<listitem>
<literal>blocked</literal> — counter of blocks held on the request.
While this value is non-zero, request cannot be terminated.
Currently, this value is increased by pending AIO operations (POSIX AIO and
thread operations) and active cache lock
</listitem>

<listitem>
<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
due to a partial string match, copy filter can buffer data because of the lack
of free output_buffers etc.
As long as this value is non-zero, request is not finalized, expecting the flush
</listitem>

<listitem>
<literal>header_only</literal> — flag showing that output does not require body.
For example, this flag is used by HTTP HEAD requests
</listitem>

<listitem>
<para>
<literal>keepalive</literal> — flag showing if client connection keepalive is
supported.
The value is inferred from HTTP version and <header>Connection</header> header
value
</para>
</listitem>

<listitem>
<literal>header_sent</literal> — flag showing that 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
redirect or be a subrequest.
Internal requests are allowed to enter internal locations
</listitem>

<listitem>
<literal>allow_ranges</literal> — flag showing that partial response can be
sent to client, if requested by the HTTP Range header
</listitem>

<listitem>
<literal>subrequest_ranges</literal> — flag showing that a partial response is
allowed to be sent while processing a subrequest
</listitem>

<listitem>
<literal>single_range</literal> — flag showing that only a single continuous
range of output data can be sent to the client.
This flag is usually set when sending a stream of data, for example from a
proxied server, and the entire response is not available at once
</listitem>

<listitem>
<literal>main_filter_need_in_memory, filter_need_in_memory</literal> — flags
showing that the output should be produced in memory buffers but not in files.
This is a signal to the copy filter to read data from file buffers even if
sendfile is enabled.
The difference between these two flags is the location of filter modules which
set them.
Filters called before the postpone filter in filter chain, set
<literal>filter_need_in_memory</literal> requesting that only the current
request output should come in memory buffers.
Filters called later in filter chain set
<literal>main_filter_need_in_memory</literal> requiring that both the main
request and all the subrequest read files in memory while sending output
</listitem>

<listitem>
<literal>filter_need_temporary</literal> — flag showing that the request output
should be produced in temporary buffers, but not in readonly memory buffers or
file buffers.
This is used by filters which may change output directly in the buffers, where
it's sent </listitem>

</list>

</section>


<section name="Configuration" id="http_conf">

<para>
Each HTTP module may have three types of configuration:
</para>

<list type="bullet">

<listitem>
Main configuration.
This configuration applies to the entire nginx http{} block.  This is global
configuration.
It stores global settings for a module
</listitem>

<listitem>
Server configuration.
This configuraion applies to a single nginx server{}.
It stores server-specific settings for a module
</listitem>

<listitem>
Location configuration.
This configuraion applies to a single location{}, if{} or limit_except() block.
This configuration stores settings specific to a location
</listitem>

</list>

<para>
Configuration structures are created at nginx configuration stage by calling
functions, which allocate these structures, initialize them and merge.
The following example shows how to create a simple module location
configuration.
The configuration has one setting <literal>foo</literal> of unsiged integer
type.
</para>

<programlisting>
typedef struct {
    ngx_uint_t  foo;
} ngx_http_foo_loc_conf_t;


static ngx_http_module_t  ngx_http_foo_module_ctx = {
    NULL,                                  /* preconfiguration */
    NULL,                                  /* postconfiguration */

    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */

    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */

    ngx_http_foo_create_loc_conf,          /* create location configuration */
    ngx_http_foo_merge_loc_conf            /* merge location configuration */
};


static void *
ngx_http_foo_create_loc_conf(ngx_conf_t *cf)
{
    ngx_http_foo_loc_conf_t  *conf;

    conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_foo_loc_conf_t));
    if (conf == NULL) {
        return NULL;
    }

    conf->foo = NGX_CONF_UNSET_UINT;

    return conf;
}


static char *
ngx_http_foo_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
{
    ngx_http_foo_loc_conf_t *prev = parent;
    ngx_http_foo_loc_conf_t *conf = child;

    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>
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.
In fact, server and location configuration do not only exist at server and
location levels, but also created for all the levels above.
Specifically, a server configuration is created at the main level as well and
location configurations are created for main, server and location levels.
These configurations make it possible to specify server and location-specific
settings at any level of nginx configuration file.
Eventually configurations are merged down.
To indicate a missing setting and ignore it while merging, nginx provides a
number of macros like <literal>NGX_CONF_UNSET</literal> and
<literal>NGX_CONF_UNSET_UINT</literal>.
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
explicit value.
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
macros are available.
They receive <literal>ngx_conf_t</literal> reference as the first argument.
</para>

<list type="bullet">

<listitem>
<literal>ngx_http_conf_get_module_main_conf(cf, module)</literal>
</listitem>

<listitem>
<literal>ngx_http_conf_get_module_srv_conf(cf, module)</literal>
</listitem>

<listitem>
<literal>ngx_http_conf_get_module_loc_conf(cf, module)</literal>
</listitem>

</list>

<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
location content handler kept in the <literal>handler</literal> field of the
structure.
</para>

<programlisting>
static ngx_int_t ngx_http_foo_handler(ngx_http_request_t *r);


static ngx_command_t  ngx_http_foo_commands[] = {

    { ngx_string("foo"),
      NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS,
      ngx_http_foo,
      0,
      0,
      NULL },

      ngx_null_command
};


static char *
ngx_http_foo(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
    ngx_http_core_loc_conf_t  *clcf;

    clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
    clcf->handler = ngx_http_bar_handler;

    return NGX_CONF_OK;
}
</programlisting>

<para>
In runtime the following macros are available to get configurations of HTTP
modules.
</para>

<list type="bullet">

<listitem>
<literal>ngx_http_get_module_main_conf(r, module)</literal>
</listitem>

<listitem>
<literal>ngx_http_get_module_srv_conf(r, module)</literal>
</listitem>

<listitem>
<literal>ngx_http_get_module_loc_conf(r, module)</literal>
</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.
Server configuration may change from a default one after choosing a virtual
server for a request.
Request location configuration may change multiple times as a result of a
rewrite or internal redirect.
The following example shows how to access HTTP configuration in runtime.
</para>

<programlisting>
static ngx_int_t
ngx_http_foo_handler(ngx_http_request_t *r)
{
    ngx_http_foo_loc_conf_t  *flcf;

    flcf = ngx_http_get_module_loc_conf(r, ngx_http_foo_module);

    ...
}
</programlisting>

</section>


<section name="Phases" id="http_phases">

<para>
Each HTTP request passes through a list of HTTP phases.
Each phase is specialized in a particular type of processing.
Most phases allow installing handlers.
The phase handlers are called successively once the request reaches the phase.
Many standard nginx modules install their phase handlers as a way to get called
at a specific request processing stage.
Following is the list of nginx HTTP phases.
</para>

<list type="bullet">

<listitem>
<literal>NGX_HTTP_POST_READ_PHASE</literal> is the earliest phase.
The <link doc="../http/ngx_http_realip_module.xml">ngx_http_realip_module</link>
installs its handler at this phase.
This allows to substitute client address before any other module is invoked
</listitem>

<listitem>
<literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal> is used to run rewrite script,
defined at the server level, that is out of any location block.
The
<link doc="../http/ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>
installs its handler at this phase
</listitem>

<listitem>
<literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> — a special phase used to choose a
location based on request URI.
This phase does not allow installing any handlers.
It only performs the default action of choosing a location.
Before this phase, the server default location is assigned to the request.
Any module requesting a location configuration, will receive the default server
location configuration.
After this phase a new location is assigned to the request
</listitem>

<listitem>
<literal>NGX_HTTP_REWRITE_PHASE</literal> — same as
<literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal>, but for a new location,
chosen at the prevous phase
</listitem>

<listitem>
<literal>NGX_HTTP_POST_REWRITE_PHASE</literal> — a special phase, used to
redirect the request to a new location, if the URI was changed during rewrite.
The redirect is done by going back to
<literal>NGX_HTTP_FIND_CONFIG_PHASE</literal>.
No handlers are allowed at this phase
</listitem>

<listitem>
<literal>NGX_HTTP_PREACCESS_PHASE</literal> — a common phase for different
types of handlers, not associated with access check.
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
</listitem>

<listitem>
<literal>NGX_HTTP_ACCESS_PHASE</literal> — used to check access permissions
for 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
<link doc="../http/ngx_http_core_module.xml" id="satisfy"/> directive, only one
of access phase handlers may allow access to the request in order to confinue
processing
</listitem>

<listitem>
<literal>NGX_HTTP_POST_ACCESS_PHASE</literal> — a special phase for the
<link doc="../http/ngx_http_core_module.xml" id="satisfy">satisfy any</link>
case.
If some access phase handlers denied the access and none of them allowed, the
request is finalized.
No handlers are supported at this phase
</listitem>

<listitem>
<literal>NGX_HTTP_TRY_FILES_PHASE</literal> — a special phase, for the
<link doc="../http/ngx_http_core_module.xml" id="try_files"/> feature.
No handlers are allowed at this phase
</listitem>

<listitem>
<literal>NGX_HTTP_CONTENT_PHASE</literal> — a phase, at which the response
is supposed to be generated.
Multiple nginx standard modules register their handers at this phase, for
example
<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
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
called as the content handler and content phase handlers are ignored
</listitem>

<listitem>
<literal>NGX_HTTP_LOG_PHASE</literal> is used to perform request logging.
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
</listitem>

</list>

<para>
Following is the example of a preaccess phase handler.
</para>

<programlisting>
static ngx_http_module_t  ngx_http_foo_module_ctx = {
    NULL,                                  /* preconfiguration */
    ngx_http_foo_init,                     /* postconfiguration */

    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */

    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */

    NULL,                                  /* create location configuration */
    NULL                                   /* merge location configuration */
};


static ngx_int_t
ngx_http_foo_handler(ngx_http_request_t *r)
{
    ngx_str_t  *ua;

    ua = r->headers_in->user_agent;

    if (ua == NULL) {
        return NGX_DECLINED;
    }

    /* reject requests with "User-Agent: foo" */
    if (ua->value.len == 3 &amp;&amp; ngx_strncmp(ua->value.data, "foo", 3) == 0) {
        return NGX_HTTP_FORBIDDEN;
    }

    return NGX_DECLINED;
}


static ngx_int_t
ngx_http_foo_init(ngx_conf_t *cf)
{
    ngx_http_handler_pt        *h;
    ngx_http_core_main_conf_t  *cmcf;

    cmcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_core_module);

    h = ngx_array_push(&amp;cmcf->phases[NGX_HTTP_PREACCESS_PHASE].handlers);
    if (h == NULL) {
        return NGX_ERROR;
    }

    *h = ngx_http_foo_handler;

    return NGX_OK;
}
</programlisting>

<para>
Phase handlers are expected to return specific codes:
</para>

<list type="bullet">

<listitem>
<literal>NGX_OK</literal> — proceed to the next phase
</listitem>

<listitem>
<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
</listitem>

<listitem>
<literal>NGX_AGAIN, NGX_DONE</literal> — suspend phase handling until some
future event.
This can be for example asynchronous I/O operation or just a delay.
It is supposed, that phase handling will be resumed later by calling
<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.
The request is finalized with the code provided
</listitem>

</list>

<para>
Some phases treat return codes in a slightly different way.
At content phase, any return code other that <literal>NGX_DECLINED</literal>
is considered a finalization code.
As for the location content handlers, any return from them is considered a
finalization code.
At access phase, in
<link doc="../http/ngx_http_core_module.xml" id="satisfy">satisfy any</link>
mode, returning a code other
than <literal>NGX_OK, NGX_DECLINED, NGX_AGAIN, NGX_DONE</literal> is considered
a denial.
If none of future access handlers allow access or deny with a new
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)
or names (see below in the section about creating variables).
Index is created at configuration stage, when a variable is added
to configuration.
The variable index can be obtained using
<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
<literal>name</literal> points to a string with the variable name.
The function returns <literal>NGX_ERROR</literal> on error or valid index
otherwise, which is typically stored somewhere in a module configuration for
future use.
</para>

<para>
All HTTP variables are evaluated in the context of HTTP request and results
are specific to and cached in HTTP request.
All functions that evaluate variables return
<literal>ngx_http_variable_value_t</literal> type, representing
the variable value:
<programlisting>
typedef ngx_variable_value_t  ngx_http_variable_value_t;

typedef struct {
    unsigned    len:28;

    unsigned    valid:1;
    unsigned    no_cacheable:1;
    unsigned    not_found:1;
    unsigned    escape:1;

    u_char     *data;
} ngx_variable_value_t;
</programlisting>
where:
<list type="bullet">

<listitem>
<literal>len</literal> — length of a value
</listitem>

<listitem>
<literal>data</literal> — value itself
</listitem>

<listitem>
<literal>valid</literal> — value is valid
</listitem>

<listitem>
<literal>not_found</literal> — 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>
when a corresponding argument was not passed in a request
</listitem>

<listitem>
<literal>no_cacheable</literal> — do not cache result
</listitem>

<listitem>
<literal>escape</literal> — used internally by the logging module to mark
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.
They have the same interface - accepting a HTTP request <literal>r</literal>
as a context for evaluating the variable and an <literal>index</literal>,
identifying it.
Example of typical usage:
<programlisting>
ngx_http_variable_value_t  *v;

v = ngx_http_get_flushed_variable(r, index);

if (v == NULL || v->not_found) {
    /* we failed to get value or there is no such variable, handle it */
    return NGX_ERROR;
}

/* some meaningful value is found */
</programlisting>
The difference between functions is that the
<literal>ngx_http_get_indexed_variable()</literal> returns cached value
and <literal>ngx_http_get_flushed_variable()</literal> flushes cache for
non-cacheable variables.
</para>

<para>
There are cases when it is required to deal with variables which names are
not known at configuration time and thus they cannot be accessed using indexes,
for example in modules like SSI or Perl.
The <literal>ngx_http_get_variable(r, name, key)</literal> function may be
used in such cases.
It searches for the <literal>variable</literal> with a given
<literal>name</literal> and its hash <literal>key</literal>.
</para>

</section>


<section name="Creating variables" id="http_creating_variables">

<para>
To create a variable <literal>ngx_http_add_variable()</literal> function
is used.
It takes configuration (where variable is registered), variable name and
flags that control its behaviour:

<list type="bullet">
<listitem><literal>NGX_HTTP_VAR_CHANGEABLE</literal>  — allows redefining
the variable; If another module will define a variable with such name,
no conflict will happen.
For example, this allows user to override variables using the
<link doc="../http/ngx_http_rewrite_module.xml" id="set"/> directive.
</listitem>

<listitem><literal>NGX_HTTP_VAR_NOCACHEABLE</literal>  — disables caching,
is useful for such variables as <literal>$time_local</literal>
</listitem>

<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
variable is not needed in modules like SSI or Perl.
</listitem>

<listitem><literal>NGX_HTTP_VAR_PREFIX</literal>  — the name of this
variable is a prefix.
A handler must implement additional logic to obtain value of specific
variable.
For example, all “<literal>arg_</literal>” variables are processed by the
same handler which performs lookup in request arguments and returns value
of specific argument.
</listitem>

</list>

The function returns NULL in case of error or a pointer to
<literal>ngx_http_variable_t</literal>:
<programlisting>
struct ngx_http_variable_s {
    ngx_str_t                     name;
    ngx_http_set_variable_pt      set_handler;
    ngx_http_get_variable_pt      get_handler;
    uintptr_t                     data;
    ngx_uint_t                    flags;
    ngx_uint_t                    index;
};
</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>index</literal> will hold assigned variable index, used to reference
the variable.
</para>

<para>
Usually, a null-terminated static array of such structures is created
by a module and processed at the preconfiguration stage to add variables
into configuration:
<programlisting>
static ngx_http_variable_t  ngx_http_foo_vars[] = {

    { ngx_string("foo_v1"), NULL, ngx_http_foo_v1_variable, NULL, 0, 0 },

    { ngx_null_string, NULL, NULL, 0, 0, 0 }
};

static ngx_int_t
ngx_http_foo_add_variables(ngx_conf_t *cf)
{
    ngx_http_variable_t  *var, *v;

    for (v = ngx_http_foo_vars; v->name.len; v++) {
        var = ngx_http_add_variable(cf, &amp;v->name, v->flags);
        if (var == NULL) {
            return NGX_ERROR;
        }

        var->get_handler = v->get_handler;
        var->data = v->data;
    }

    return NGX_OK;
}
</programlisting>
This function is used to initialize the <literal>preconfiguration</literal>
field of the HTTP module context and is called before parsing HTTP configuration,
so it could refer to these variables.
</para>

<para>
The <literal>get</literal> handler is responsible for evaluating the variable
in a context of 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)
{
    u_char  *p;

    p = ngx_pnalloc(r->pool, NGX_ATOMIC_T_LEN);
    if (p == NULL) {
        return NGX_ERROR;
    }

    v->len = ngx_sprintf(p, "%uA", r->connection->number) - p;
    v->valid = 1;
    v->no_cacheable = 0;
    v->not_found = 0;
    v->data = p;

    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
of the <literal>ngx_http_variable_value_t</literal> (see description above).
</para>

<para>
The <literal>set</literal> handler allows setting the property
referred by the variable.
For example, the <literal>$limit_rate</literal> variable set handler
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,
  offsetof(ngx_http_request_t, limit_rate),
  NGX_HTTP_VAR_CHANGEABLE|NGX_HTTP_VAR_NOCACHEABLE, 0 },
...

static void
ngx_http_variable_request_set_size(ngx_http_request_t *r,
    ngx_http_variable_value_t *v, uintptr_t data)
{
    ssize_t    s, *sp;
    ngx_str_t  val;

    val.len = v->len;
    val.data = v->data;

    s = ngx_parse_size(&amp;val);

    if (s == NGX_ERROR) {
        ngx_log_error(NGX_LOG_ERR, r->connection->log, 0,
                      "invalid size \"%V\"", &amp;val);
        return;
    }

    sp = (ssize_t *) ((char *) r + data);

    *sp = s;

    return;
}
</programlisting>

</para>

</section>

</section>


<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.
</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.

<programlisting>
ngx_str_t                         *value;
ngx_http_complex_value_t           cv;
ngx_http_compile_complex_value_t   ccv;

value = cf->args->elts; /* directive arguments */

ngx_memzero(&amp;ccv, sizeof(ngx_http_compile_complex_value_t));

ccv.cf = cf;
ccv.value = &amp;value[1];
ccv.complex_value = &amp;cv;
ccv.zero = 1;
ccv.conf_prefix = 1;

if (ngx_http_compile_complex_value(&amp;ccv) != NGX_OK) {
    return NGX_CONF_ERROR;
}
</programlisting>

Here, <literal>ccv</literal> holds all parameters that are required to
initialize the complex value <literal>cv</literal>:

<list type="bullet">

<listitem>
<literal>cf</literal> — configuration pointer
</listitem>

<listitem>
<literal>value</literal> — string for parsing (input)
</listitem>

<listitem>
<literal>complex_value</literal> — compiled value (output)
</listitem>

<listitem>
<literal>zero</literal> — flag that enables zero-terminating value
</listitem>

<listitem>
<literal>conf_prefix</literal> — prefixes result with configuration prefix
(the directory where nginx is currently looking for configuration)
</listitem>

<listitem>
<literal>root_prefix</literal> — prefixes result with root prefix
(this is the normal nginx installation prefix)
</listitem>

</list>
The <literal>zero</literal> flag is usable 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
be inspected to get 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,
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
declaration.
</para>

<para>
At runtime, a complex value may 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
expression and put result into <literal>res</literal>.
</para>

</section>


<section name="Request redirection" id="http_request_redirection">

<para>
An HTTP request is always connected to a location via the
<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.
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
<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
<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
return to the <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> phase for choosing 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
<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 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.
</para>

<para>
The following example performs an internal redirect with the new request
arguments.
</para>

<programlisting>
ngx_int_t
ngx_http_foo_redirect(ngx_http_request_t *r)
{
    ngx_str_t  uri, args;

    ngx_str_set(&amp;uri, "/foo");
    ngx_str_set(&amp;args, "bar=1");

    return ngx_http_internal_redirect(r, &amp;uri, &amp;args);
}
</programlisting>

<para>
The function <literal>ngx_http_named_location(r, name)</literal> redirects
a request to a named location.  The name of the location is passed as the
argument.  The location is looked up among all named locations of the current
server, after which the requests switches to the
<literal>NGX_HTTP_REWRITE_PHASE</literal> phase.
</para>

<para>
The following example performs a redirect to a named location @foo.
</para>

<programlisting>
ngx_int_t
ngx_http_foo_named_redirect(ngx_http_request_t *r)
{
    ngx_str_t  name;

    ngx_str_set(&amp;name, "foo");

    return ngx_http_named_location(r, &amp;name);
}
</programlisting>

<para>
Both functions <literal>ngx_http_internal_redirect(r, uri, args)</literal>
and <literal>ngx_http_named_location(r, name)</literal> may be called when
a request already has some contexts saved in its <literal>ctx</literal> field
by nginx modules.  These contexts could become inconsistent with the new
location configuration.  To prevent inconsistency, all request contexts are
erased by both redirect functions.
</para>

<para>
Redirected and rewritten requests become internal and may 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>


<section name="Subrequests" id="http_subrequests">

<para>
Subrequests are primarily used to include 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
does not receive any other input from client.
The request field <literal>parent</literal> for a subrequest keeps a link 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
requests.
</para>

<para>
A subrequest starts with <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal> phase.
It passes through the same phases as a normal request and is assigned a location
based on its own URI.
</para>

<para>
Subrequest output header is always ignored.
Subrequest output body is placed by the
<literal>ngx_http_postpone_filter</literal> into the right position in relation
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
its buffers to the client.
A non-active request can still send its data to the filter chain, but they
will not pass beyond the <literal>ngx_http_postpone_filter</literal> and will
remain 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
</listitem>

<listitem>
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
sent
</listitem>

<listitem>
When a request is finalized, its parent is activated
</listitem>

</list>

<para>
A subrequest is created 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
subrequest, <literal>psr</literal> is the output parameter, receiving the
newly created subrequest reference, <literal>ps</literal> is a callback object
for notifying the parent request that the subrequest is being finalized,
<literal>flags</literal> is subrequest creation flags bitmask.
The following flags are available:
</para>

<list type="bullet">

<listitem>
<literal>NGX_HTTP_SUBREQUEST_IN_MEMORY</literal> - subrequest output should not
be sent to the client, but rather stored in memory.
This only works for proxying subrequests.
After subrequest finalization its output is available in
<literal>r->upstream->buffer</literal> buffer of type
<literal>ngx_buf_t</literal>
</listitem>

<listitem>
<literal>NGX_HTTP_SUBREQUEST_WAITED</literal> - the subrequest
<literal>done</literal> flag is set even if it is finalized being non-active.
This subrequest flag is used by the SSI filter
</listitem>

<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
</listitem>

</list>

<para>
The following example creates a subrequest with the URI of "/foo".
</para>

<programlisting>
ngx_int_t            rc;
ngx_str_t            uri;
ngx_http_request_t  *sr;

...

ngx_str_set(&amp;uri, "/foo");

rc = ngx_http_subrequest(r, &amp;uri, NULL, &amp;sr, NULL, 0);
if (rc == NGX_ERROR) {
    /* error */
}
</programlisting>

<para>
This example clones the current request and sets a finalization callback for the
subrequest.
</para>

<programlisting>
ngx_int_t
ngx_http_foo_clone(ngx_http_request_t *r)
{
    ngx_http_request_t          *sr;
    ngx_http_post_subrequest_t  *ps;

    ps = ngx_palloc(r->pool, sizeof(ngx_http_post_subrequest_t));
    if (ps == NULL) {
        return NGX_ERROR;
    }

    ps->handler = ngx_http_foo_subrequest_done;
    ps->data = "foo";

    return ngx_http_subrequest(r, &amp;r->uri, &amp;r->args, &amp;sr, ps,
                               NGX_HTTP_SUBREQUEST_CLONE);
}


ngx_int_t
ngx_http_foo_subrequest_done(ngx_http_request_t *r, void *data, ngx_int_t rc)
{
    char  *msg = (char *) data;

    ngx_log_error(NGX_LOG_INFO, r->connection->log, 0,
                  "done subrequest r:%p msg:%s rc:%i", r, msg, rc);

    return rc;
}
</programlisting>

<para>
Subrequests are normally created in a body filter.
In this case subrequest output can be treated as any other explicit request
output.
This means that eventually the output of a subrequest is sent to the client
after all explicit buffers passed prior to subrequest creation and before any
buffers passed later.
This ordering is preserved even for large hierarchies of subrequests.
The following example inserts a subrequest output after all request data
buffers, but before the final buffer with the <literal>last_buf</literal> flag.
</para>

<programlisting>
ngx_int_t
ngx_http_foo_body_filter(ngx_http_request_t *r, ngx_chain_t *in)
{
    ngx_int_t                   rc;
    ngx_buf_t                  *b;
    ngx_uint_t                  last;
    ngx_chain_t                *cl, out;
    ngx_http_request_t         *sr;
    ngx_http_foo_filter_ctx_t  *ctx;

    ctx = ngx_http_get_module_ctx(r, ngx_http_foo_filter_module);
    if (ctx == NULL) {
        return ngx_http_next_body_filter(r, in);
    }

    last = 0;

    for (cl = in; cl; cl = cl->next) {
        if (cl->buf->last_buf) {
            cl->buf->last_buf = 0;
            cl->buf->last_in_chain = 1;
            cl->buf->sync = 1;
            last = 1;
        }
    }

    /* Output explicit output buffers */

    rc = ngx_http_next_body_filter(r, in);

    if (rc == NGX_ERROR || !last) {
        return rc;
    }

    /*
     * Create the subrequest.  The output of the subrequest
     * will automatically be sent after all preceding buffers,
     * but before the last_buf buffer passed later in this function.
     */

    if (ngx_http_subrequest(r, ctx->uri, NULL, &amp;sr, NULL, 0) != NGX_OK) {
        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;
    }

    b->last_buf = 1;

    out.buf = b;
    out.next = NULL;

    return ngx_http_output_filter(r, &amp;out);
}
</programlisting>

<para>
A subrequest may 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>
creates a subrequest at <literal>NGX_HTTP_ACCESS_PHASE</literal> phase.
To disable any output at this point, the subrequest
<literal>header_only</literal> flag is set.
This prevents subrequest body from being sent to the client.
Its header is ignored anyway.
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
to the filter chain.
At this point the output may not be completely sent to the client, but remain
buffered somewhere along the filter chain.
If it is, the <literal>ngx_http_finalize_request(r, rc)</literal> function will
automatically install 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>
The function <literal>ngx_http_finalize_request(r, rc)</literal> expects the
following <literal>rc</literal> values:
</para>

<list type="bullet">

<listitem>
<literal>NGX_DONE</literal> - fast finalization.
Decrement request <literal>count</literal> and destroy the request if it
reaches zero.
The client connection may still be used for more requests after that
</listitem>

<listitem>
<literal>NGX_ERROR</literal>, <literal>NGX_HTTP_REQUEST_TIME_OUT</literal>
(408), <literal>NGX_HTTP_CLIENT_CLOSED_REQUEST</literal> (499) - 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_NO_CONTENT</literal> (204), codes greater than or equal to
<literal>NGX_HTTP_SPECIAL_RESPONSE</literal> (300) - special response
finalization.
For these values nginx either sends a default code response page to the client
or performs the internal redirect to an
<link doc="../http/ngx_http_core_module.xml" id="error_page"/> location if it's
configured for the code
</listitem>

<listitem>
Other codes are considered success finalization codes and may activate the
request writer to finish sending the response body.
Once body is completely sent, request <literal>count</literal> is decremented.
If it reaches zero, the request is destroyed, but the client connection may
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>

</list>

</section>


<section name="Request body" id="http_request_body">

<para>
For dealing with client request body, nginx provides the following functions:
<literal>ngx_http_read_client_request_body(r, post_handler)</literal> and
<literal>ngx_http_discard_request_body(r)</literal>.
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.
</para>

<para>
Reading or discarding client request body from a subrequest is not allowed.
It should always be done in the main request.
When a subrequest is created, it inherits the parent
<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.
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
<link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/>
is not enough to fit the entire body in memory.
</para>

<para>
The following example reads client request body and returns its size.
</para>

<programlisting>
ngx_int_t
ngx_http_foo_content_handler(ngx_http_request_t *r)
{
    ngx_int_t  rc;

    rc = ngx_http_read_client_request_body(r, ngx_http_foo_init);

    if (rc >= NGX_HTTP_SPECIAL_RESPONSE) {
        /* error */
        return rc;
    }

    return NGX_DONE;
}


void
ngx_http_foo_init(ngx_http_request_t *r)
{
    off_t         len;
    ngx_buf_t    *b;
    ngx_int_t     rc;
    ngx_chain_t  *in, out;

    if (r->request_body == NULL) {
        ngx_http_finalize_request(r, NGX_HTTP_INTERNAL_SERVER_ERROR);
        return;
    }

    len = 0;

    for (in = r->request_body->bufs; in; in = in->next) {
        len += ngx_buf_size(in->buf);
    }

    b = ngx_create_temp_buf(r->pool, NGX_OFF_T_LEN);
    if (b == NULL) {
        ngx_http_finalize_request(r, NGX_HTTP_INTERNAL_SERVER_ERROR);
        return;
    }

    b->last = ngx_sprintf(b->pos, "%O", len);
    b->last_buf = (r == r->main) ? 1: 0;
    b->last_in_chain = 1;

    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = b->last - b->pos;

    rc = ngx_http_send_header(r);

    if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
        ngx_http_finalize_request(r, rc);
        return;
    }

    out.buf = b;
    out.next = NULL;

    rc = ngx_http_output_filter(r, &amp;out);

    ngx_http_finalize_request(r, rc);
}
</programlisting>

<para>
The following fields of the request affect the way request body is read:
</para>

<list type="bullet">

<listitem>
<literal>request_body_in_single_buf</literal> - read body to a single memory
buffer
</listitem>

<listitem>
<literal>request_body_in_file_only</literal> - always read body to a file,
even if fits the memory buffer
</listitem>

<listitem>
<literal>request_body_in_persistent_file</literal> - do not unlink the file
right after creation.
Such a file can be moved to another directory
</listitem>

<listitem>
<literal>request_body_in_clean_file</literal> - unlink the file the 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
</listitem>

<listitem>
<literal>request_body_file_group_access</literal> - enable file group access.
By default a file is created with 0600 access mask.
When the flag is set, 0660 access mask is used
</listitem>

<listitem>
<literal>request_body_file_log_level</literal> - log file errors with this
log level
</listitem>

<listitem>
<literal>request_body_no_buffering</literal> - read request body without
buffering
</listitem>

</list>

<para>
When the <literal>request_body_no_buffering</literal> flag is set, the
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.
To read the next part, the
<literal>ngx_http_read_unbuffered_request_body(r)</literal> function should be
called.
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.
</para>

</section>


<section name="Response" id="http_response">

<para>
An HTTP response in nginx 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.
</para>


<section name="Response header" id="http_response_header">

<para>
Output header is sent by the function
<literal>ngx_http_send_header(r)</literal>.
Prior to calling this function, <literal>r->headers_out</literal> should contain
all the data required to produce the HTTP response header.
It's always required to set the <literal>status</literal> field of
<literal>r->headers_out</literal>.
If the response status suggests 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
unknown.
In this case, chunked transfer encoding is used.
To output an arbitrary header, <literal>headers</literal> list should be
appended.
</para>

<programlisting>
static ngx_int_t
ngx_http_foo_content_handler(ngx_http_request_t *r)
{
    ngx_int_t         rc;
    ngx_table_elt_t  *h;

    /* send header */

    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = 3;

    /* X-Foo: foo */

    h = ngx_list_push(&amp;r->headers_out.headers);
    if (h == NULL) {
        return NGX_ERROR;
    }

    h->hash = 1;
    ngx_str_set(&amp;h->key, "X-Foo");
    ngx_str_set(&amp;h->value, "foo");

    rc = ngx_http_send_header(r);

    if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
        return rc;
    }

    /* send body */

    ...
}
</programlisting>

</section>


<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
<literal>ngx_http_top_header_filter</literal>.
It's assumed that every header handler calls the next handler in chain 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
<literal>ngx_http_top_header_filter</literal> global variable at configuration
time.
The previous handler address is normally stored in a module's static variable
and is called by the newly added handler before exiting.
</para>

<para>
The following is an example header filter module, adding the HTTP header
"X-Foo: foo" to every output with the status 200.
</para>

<programlisting>
#include &lt;ngx_config.h&gt;
#include &lt;ngx_core.h&gt;
#include &lt;ngx_http.h&gt;


static ngx_int_t ngx_http_foo_header_filter(ngx_http_request_t *r);
static ngx_int_t ngx_http_foo_header_filter_init(ngx_conf_t *cf);


static ngx_http_module_t  ngx_http_foo_header_filter_module_ctx = {
    NULL,                                   /* preconfiguration */
    ngx_http_foo_header_filter_init,        /* postconfiguration */

    NULL,                                   /* create main configuration */
    NULL,                                   /* init main configuration */

    NULL,                                   /* create server configuration */
    NULL,                                   /* merge server configuration */

    NULL,                                   /* create location configuration */
    NULL                                    /* merge location configuration */
};


ngx_module_t  ngx_http_foo_header_filter_module = {
    NGX_MODULE_V1,
    &amp;ngx_http_foo_header_filter_module_ctx, /* module context */
    NULL,                                   /* module directives */
    NGX_HTTP_MODULE,                        /* module type */
    NULL,                                   /* init master */
    NULL,                                   /* init module */
    NULL,                                   /* init process */
    NULL,                                   /* init thread */
    NULL,                                   /* exit thread */
    NULL,                                   /* exit process */
    NULL,                                   /* exit master */
    NGX_MODULE_V1_PADDING
};


static ngx_http_output_header_filter_pt  ngx_http_next_header_filter;


static ngx_int_t
ngx_http_foo_header_filter(ngx_http_request_t *r)
{
    ngx_table_elt_t  *h;

    /* 
     * The filter handler adds "X-Foo: foo" header
     * to every HTTP 200 response
     */

    if (r->headers_out.status != NGX_HTTP_OK) {
        return ngx_http_next_header_filter(r);
    }

    h = ngx_list_push(&amp;r->headers_out.headers);
    if (h == NULL) {
        return NGX_ERROR;
    }

    h->hash = 1;
    ngx_str_set(&amp;h->key, "X-Foo");
    ngx_str_set(&amp;h->value, "foo");

    return ngx_http_next_header_filter(r);
}


static ngx_int_t
ngx_http_foo_header_filter_init(ngx_conf_t *cf)
{
    ngx_http_next_header_filter = ngx_http_top_header_filter;
    ngx_http_top_header_filter = ngx_http_foo_header_filter;

    return NGX_OK;
}
</programlisting>

</section>

</section>


<section name="Response body" id="http_response_body">

<para>
Response body is sent by calling the function
<literal>ngx_http_output_filter(r, cl)</literal>.
The function can be called multiple times.
Each time it sends a part of the response body passed as a buffer chain.
The last body buffer should have the <literal>last_buf</literal> flag set.
</para>

<para>
The following example produces a complete HTTP output with "foo" as its body.
In order for the example to work not only as a main request but as a subrequest
as well, the <literal>last_in_chain_flag</literal> is set in the last buffer
of the output.
The <literal>last_buf</literal> flag is set only for the main request since
a subrequest's last buffers does not end the entire output.
</para>

<programlisting>
static ngx_int_t
ngx_http_bar_content_handler(ngx_http_request_t *r)
{
    ngx_int_t     rc;
    ngx_buf_t    *b;
    ngx_chain_t   out;

    /* send header */

    r->headers_out.status = NGX_HTTP_OK;
    r->headers_out.content_length_n = 3;

    rc = ngx_http_send_header(r);

    if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
        return rc;
    }

    /* send body */

    b = ngx_calloc_buf(r->pool);
    if (b == NULL) {
        return NGX_ERROR;
    }

    b->last_buf = (r == r->main) ? 1: 0;
    b->last_in_chain = 1;

    b->memory = 1;

    b->pos = (u_char *) "foo";
    b->last = b->pos + 3;

    out.buf = b;
    out.next = NULL;

    return ngx_http_output_filter(r, &amp;out);
}
</programlisting>

</section>


<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
<literal>ngx_http_top_body_filter</literal>.
It's assumed that every body handler calls the next handler in 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.
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,
a handler should allocate its own chain links.
</para>

<para>
Following is the example of a simple body filter counting the number of
body bytes.
The result is available as the <literal>$counter</literal> variable which can be
used in the access log.
</para>

<programlisting>
#include &lt;ngx_config.h&gt;
#include &lt;ngx_core.h&gt;
#include &lt;ngx_http.h&gt;


typedef struct {
    off_t  count;
} ngx_http_counter_filter_ctx_t;


static ngx_int_t ngx_http_counter_body_filter(ngx_http_request_t *r,
    ngx_chain_t *in);
static ngx_int_t ngx_http_counter_variable(ngx_http_request_t *r,
    ngx_http_variable_value_t *v, uintptr_t data);
static ngx_int_t ngx_http_counter_add_variables(ngx_conf_t *cf);
static ngx_int_t ngx_http_counter_filter_init(ngx_conf_t *cf);


static ngx_http_module_t  ngx_http_counter_filter_module_ctx = {
    ngx_http_counter_add_variables,        /* preconfiguration */
    ngx_http_counter_filter_init,          /* postconfiguration */

    NULL,                                  /* create main configuration */
    NULL,                                  /* init main configuration */

    NULL,                                  /* create server configuration */
    NULL,                                  /* merge server configuration */

    NULL,                                  /* create location configuration */
    NULL                                   /* merge location configuration */
};


ngx_module_t  ngx_http_counter_filter_module = {
    NGX_MODULE_V1,
    &amp;ngx_http_counter_filter_module_ctx,   /* module context */
    NULL,                                  /* module directives */
    NGX_HTTP_MODULE,                       /* module type */
    NULL,                                  /* init master */
    NULL,                                  /* init module */
    NULL,                                  /* init process */
    NULL,                                  /* init thread */
    NULL,                                  /* exit thread */
    NULL,                                  /* exit process */
    NULL,                                  /* exit master */
    NGX_MODULE_V1_PADDING
};


static ngx_http_output_body_filter_pt  ngx_http_next_body_filter;

static ngx_str_t  ngx_http_counter_name = ngx_string("counter");


static ngx_int_t
ngx_http_counter_body_filter(ngx_http_request_t *r, ngx_chain_t *in)
{
    ngx_chain_t                    *cl;
    ngx_http_counter_filter_ctx_t  *ctx;

    ctx = ngx_http_get_module_ctx(r, ngx_http_counter_filter_module);
    if (ctx == NULL) {
        ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_counter_filter_ctx_t));
        if (ctx == NULL) {
            return NGX_ERROR;
        }

        ngx_http_set_ctx(r, ctx, ngx_http_counter_filter_module);
    }

    for (cl = in; cl; cl = cl->next) {
        ctx->count += ngx_buf_size(cl->buf);
    }

    return ngx_http_next_body_filter(r, in);
}


static ngx_int_t
ngx_http_counter_variable(ngx_http_request_t *r, ngx_http_variable_value_t *v,
    uintptr_t data)
{
    u_char                         *p;
    ngx_http_counter_filter_ctx_t  *ctx;

    ctx = ngx_http_get_module_ctx(r, ngx_http_counter_filter_module);
    if (ctx == NULL) {
        v->not_found = 1;
        return NGX_OK;
    }

    p = ngx_pnalloc(r->pool, NGX_OFF_T_LEN);
    if (p == NULL) {
        return NGX_ERROR;
    }

    v->data = p;
    v->len = ngx_sprintf(p, "%O", ctx->count) - p;
    v->valid = 1;
    v->no_cacheable = 0;
    v->not_found = 0;

    return NGX_OK;
}


static ngx_int_t
ngx_http_counter_add_variables(ngx_conf_t *cf)
{
    ngx_http_variable_t  *var;

    var = ngx_http_add_variable(cf, &amp;ngx_http_counter_name, 0);
    if (var == NULL) {
        return NGX_ERROR;
    }

    var->get_handler = ngx_http_counter_variable;

    return NGX_OK;
}


static ngx_int_t
ngx_http_counter_filter_init(ngx_conf_t *cf)
{
    ngx_http_next_body_filter = ngx_http_top_body_filter;
    ngx_http_top_body_filter = ngx_http_counter_body_filter;

    return NGX_OK;
}
</programlisting>

</section>


<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
filters 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
other filters.
Normally, filters are registered by modules in their postconfiguration handlers.
The order in which filters are called is obviously the reverse of when they are
registered.
</para>

<para>
A special slot <literal>HTTP_AUX_FILTER_MODULES</literal> for third-party filter
modules is provided by nginx.
To register a filter module in this slot, the <literal>ngx_module_type</literal>
variable should be set to the value of <literal>HTTP_AUX_FILTER</literal> in
module's configuration.
</para>

<para>
The following example shows a filter module config file assuming it only has
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
ngx_module_srcs="$ngx_addon_dir/ngx_http_foo_filter_module.c"

. auto/module
</programlisting>

</section>


<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
for this purpose: <literal>free</literal> and <literal>busy</literal>.
The <literal>free</literal> chain keeps all free buffers.
These buffers 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.
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,
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
<literal>ngx_chain_update_chains(free, busy, out, tag)</literal> which does
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.
This lets a module reuse only the buffers allocated by itself.
</para>

<para>
The following example is a body filter inserting the “foo” string 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
header filter and reset <literal>content_length_n</literal> to -1, which is
beyond the scope of this section.
</para>

<programlisting>
typedef struct {
    ngx_chain_t  *free;
    ngx_chain_t  *busy;
}  ngx_http_foo_filter_ctx_t;


ngx_int_t
ngx_http_foo_body_filter(ngx_http_request_t *r, ngx_chain_t *in)
{
    ngx_int_t                   rc;
    ngx_buf_t                  *b;
    ngx_chain_t                *cl, *tl, *out, **ll;
    ngx_http_foo_filter_ctx_t  *ctx;

    ctx = ngx_http_get_module_ctx(r, ngx_http_foo_filter_module);
    if (ctx == NULL) {
        ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_foo_filter_ctx_t));
        if (ctx == NULL) {
            return NGX_ERROR;
        }

        ngx_http_set_ctx(r, ctx, ngx_http_foo_filter_module);
    }

    /* create a new chain "out" from "in" with all the changes */

    ll = &amp;out;

    for (cl = in; cl; cl = cl->next) {

        /* append "foo" in a reused buffer if possible */

        tl = ngx_chain_get_free_buf(r->pool, &amp;ctx->free);
        if (tl == NULL) {
            return NGX_ERROR;
        }

        b = tl->buf;
        b->tag = (ngx_buf_tag_t) &amp;ngx_http_foo_filter_module;
        b->memory = 1;
        b->pos = (u_char *) "foo";
        b->last = b->pos + 3;

        *ll = tl;
        ll = &amp;tl->next;

        /* append the next incoming buffer */

        tl = ngx_alloc_chain_link(r->pool);
        if (tl == NULL) {
            return NGX_ERROR;
        }

        tl->buf = cl->buf;
        *ll = tl;
        ll = &amp;tl->next;
    }

    *ll = NULL;

    /* send the new chain */

    rc = ngx_http_next_body_filter(r, out);

    /* update "busy" and "free" chains for reuse */

    ngx_chain_update_chains(r->pool, &amp;ctx->free, &amp;ctx->busy, &amp;out,
                            (ngx_buf_tag_t) &amp;ngx_http_foo_filter_module);

    return rc;
}
</programlisting>

</section>


<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.
This functionality is used by modules that implement specific protocols,
such as HTTP or FastCGI.
The module also provides an interface for creating custom
load balancing modules and implements a default round-robin balancing method.
</para>

<para>
Examples of modules that implement alternative load balancing methods are
<link doc="../http/ngx_http_upstream_module.xml" id="least_conn"/>
and <link doc="../http/ngx_http_upstream_module.xml" id="hash"/>.
Note that these modules are actually implemented as extensions of the upstream
module and share a lot of code, such as 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.
</para>

<para>
The
<link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link>
may 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,
for example,
<link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/>.
Only explicit configurations may use an alternative load balancing method.
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 {
    ngx_http_upstream_peer_t         peer;
    void                           **srv_conf;

    ngx_array_t                     *servers;  /* ngx_http_upstream_server_t */

    ngx_uint_t                       flags;
    ngx_str_t                        host;
    u_char                          *file_name;
    ngx_uint_t                       line;
    in_port_t                        port;
    ngx_uint_t                       no_port;  /* unsigned no_port:1 */

#if (NGX_HTTP_UPSTREAM_ZONE)
    ngx_shm_zone_t                  *shm_zone;
#endif
};
</programlisting>

<list type="bullet">

<listitem>
<literal>srv_conf</literal> — configuration context of upstream modules
</listitem>

<listitem>
<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
</listitem>

<listitem>
<literal>flags</literal> — flags that mostly mark which features
(configured as parameters of
the <link doc="../http/ngx_http_upstream_module.xml" id="server"/> directive)
are supported by the particular load balancing method.

<list type="bullet">

<listitem>
<literal>NGX_HTTP_UPSTREAM_CREATE</literal> — used to distinguish explicitly
defined upstreams from automatically created by
<link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/> and “friends”
(FastCGI, SCGI, etc.)
</listitem>

<listitem>
<literal>NGX_HTTP_UPSTREAM_WEIGHT</literal> — “<literal>weight</literal>”
is supported
</listitem>

<listitem>
<literal>NGX_HTTP_UPSTREAM_MAX_FAILS</literal> — “<literal>max_fails</literal>”
is supported
</listitem>

<listitem>
<literal>NGX_HTTP_UPSTREAM_FAIL_TIMEOUT</literal> —
“<literal>fail_timeout</literal>” is supported
</listitem>

<listitem>
<literal>NGX_HTTP_UPSTREAM_DOWN</literal> — “<literal>down</literal>”
is supported
</listitem>

<listitem>
<literal>NGX_HTTP_UPSTREAM_BACKUP</literal> — “<literal>backup</literal>”
is supported
</listitem>

<listitem>
<literal>NGX_HTTP_UPSTREAM_MAX_CONNS</literal> — “<literal>max_conns</literal>”
is supported
</listitem>

</list>

</listitem>

<listitem>
<literal>host</literal> — the name of an upstream
</listitem>

<listitem>
<literal>file_name, line</literal> — the name of the configuration file
and the line where the <literal>upstream</literal> block is located
</listitem>

<listitem>
<literal>port</literal> and <literal>no_port</literal> — unused by explicit
upstreams
</listitem>

<listitem>
<literal>shm_zone</literal> — a shared memory zone used by this upstream, if any
</listitem>

<listitem>
<literal>peer</literal> — an 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
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
<literal>ngx_http_upstream_init_round_robin</literal>.

<list type="bullet">
<listitem>
<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
to create some efficient data structure that it uses and saves own
configuration to the <literal>data</literal> field.
</listitem>

<listitem>
<literal>init(r, us)</literal> — initializes per-request
<literal>ngx_http_upstream_peer_t.peer</literal> (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.
It will be passed as <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 method is taken from the
<literal>ngx_http_upstream_peer_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;

    ngx_uint_t                       tries;

    ngx_event_get_peer_pt            get;
    ngx_event_free_peer_pt           free;
    ngx_event_notify_peer_pt         notify;
    void                            *data;

#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;
this is the output parameter of a load balancing method
</listitem>

<listitem>
<literal>data</literal> — per-request load balancing method data; keeps the
state of selection algorithm and usually includes the link to upstream
configuration.
It will be passed as an argument to all methods that deal with server selection
(see below)
</listitem>

<listitem>
<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.
</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
</listitem>

</list>

</para>

<para>
All methods accept at least two arguments: 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
to “chaining” of load balancing modules.
</para>

<para>

<list type="bullet">
<listitem>
<literal>get(pc, data)</literal> — the method is 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>,
<literal>socklen</literal>, and <literal>name</literal> fields of
<literal>ngx_peer_connection_t</literal> structure.
The return value may be one of:

<list type="bullet">

<listitem>
<literal>NGX_OK</literal> — server was selected
</listitem>

<listitem>
<literal>NGX_ERROR</literal> — internal error occurred
</listitem>

<listitem>
<literal>NGX_BUSY</literal> — there are no available servers at the moment.
This can happen due to many reasons, such as: dynamic server group is empty,
all servers in the group are in the failed state,
all servers in the group are already
handling the maximum number of connections or similar.
</listitem>

<listitem>
<literal>NGX_DONE</literal> — this is set by the <literal>keepalive</literal>
module to indicate that the underlying connection was reused and there is no
need to create a new connection to the upstream server.
</listitem>

<!--
<listitem>
<literal>NGX_ABORT</literal> — this is set by the <literal>queue</literal>
module to indicate that the request was queued and the further processing
of this request should be postponed.
</listitem>
-->

</list>

</listitem>

<listitem>
<literal>free(pc, data, state)</literal> — the method is called when an
upstream module has finished work with a particular server.
The <literal>state</literal> argument is the status of upstream connection
completion.
This is a bitmask, the following values may be set:
<literal>NGX_PEER_FAILED</literal> — this attempt is considered
<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
(see link above), which are not considered a failure.
<literal>NGX_PEER_KEEPALIVE</literal>.
Also, <literal>tries</literal> counter is decremented by this method.
</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
servers.
The implementation is provided by the round-robin balancing method.
</listitem>

</list>

</para>

</section>

</section>

</article>