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

annotate xml/en/docs/dev/development_guide.xml @ 2151:ed6b44206600

Clarified the "zone_sync_server" directive description.

author	Vladimir Homutov <vl@nginx.com>
date	Mon, 16 Apr 2018 14:19:35 +0300
parents	c07cd947402f
children	ccc41545bf55

rev	line source
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1 <?xml version="1.0"?>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	3 <!--
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	4 Copyright (C) Nginx, Inc.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	5 -->
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	6
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	8
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	9 <article name="Development guide"
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	10 link="/en/docs/dev/development_guide.html"
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	11 lang="en"
2151 ed6b44206600 Clarified the "zone_sync_server" directive description. Vladimir Homutov <vl@nginx.com> parents: 2146 diff changeset	12 rev="3">
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	13
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	14 <section name="Introduction" id="introduction">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	15
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	16
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	17 <section name="Code layout" id="code_layout">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	18
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	19 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	20 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	21 <literal>auto</literal> — Build scripts
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	22 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	23
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	24 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	25 <literal>src</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	26
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	27 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	28
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	29 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	30 <literal>core</literal> — Basic types and functions — string, array, log,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	31 pool, etc.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	32 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	33
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	34 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	35 <literal>event</literal> — Event core
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	36
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	37 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	38
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	39 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	40 <literal>modules</literal> — Event notification modules:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	41 <literal>epoll</literal>, <literal>kqueue</literal>, <literal>select</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	42 etc.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	43 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	44
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	45 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	46
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	47 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	48
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	49 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	50 <literal>http</literal> — Core HTTP module and common code
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	51
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	52 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	53
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	54 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	55 <literal>modules</literal> — Other HTTP modules
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	56 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	57
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	58 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	59 <literal>v2</literal> — HTTP/2
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	60 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	61
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	62 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	63
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	64 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	65
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	66 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	67 <literal>mail</literal> — Mail modules
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	68 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	69
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	70 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	71 <literal>os</literal> — Platform-specific code
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	72
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	73 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	74
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	75 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	76 <literal>unix</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	77 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	78
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	79 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	80 <literal>win32</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	81 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	82
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	83 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	84
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	85 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	86
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	87 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	88 <literal>stream</literal> — Stream modules
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	89 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	90
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	91 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	92
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	93 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	94
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	95 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	96
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	97 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	98
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	99
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	100 <section name="Include files" id="include_files">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	101
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	102 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	103 The following two <literal>#include</literal> statements must appear at the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	104 beginning of every nginx file:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	105 </para>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	106
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	107 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	108 #include <ngx_config.h>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	109 #include <ngx_core.h>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	110 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	111
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	112 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	113 In addition to that, HTTP code should include
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	114 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	115
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	116
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	117 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	118 #include <ngx_http.h>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	119 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	120
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	121 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	122 Mail code should include
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	123 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	124
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	125
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	126 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	127 #include <ngx_mail.h>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	128 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	129
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	130 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	131 Stream code should include
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	132 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	133
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	134
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	135 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	136 #include <ngx_stream.h>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	137 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	138
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	139 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	140
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	141
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	142 <section name="Integers" id="integers">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	143
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	144 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	145 For general purposes, nginx code uses two integer types,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	146 <literal>ngx_int_t</literal> and <literal>ngx_uint_t</literal>, which are
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	147 typedefs for <literal>intptr_t</literal> and <literal>uintptr_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	148 respectively.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	149 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	150
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	151 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	152
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	153
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	154 <section name="Common return codes" id="common_return_codes">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	155
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	156 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	157 Most functions in nginx return the following codes:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	158 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	159
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	160 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	161
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	162 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	163 <literal>NGX_OK</literal> — Operation succeeded.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	164 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	165
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	166 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	167 <literal>NGX_ERROR</literal> — Operation failed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	168 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	169
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	170 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	171 <literal>NGX_AGAIN</literal> — Operation incomplete; call the function again.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	172 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	173
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	174 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	175 <literal>NGX_DECLINED</literal> — Operation rejected, for example, because it is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	176 disabled in the configuration. This is never an error.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	177 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	178
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	179 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	180 <literal>NGX_BUSY</literal> — Resource is not available.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	181 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	182
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	183 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	184 <literal>NGX_DONE</literal> — Operation complete or continued elsewhere.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	185 Also used as an alternative success code.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	186 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	187
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	188 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	189 <literal>NGX_ABORT</literal> — Function was aborted.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	190 Also used as an alternative error code.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	191 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	192
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	193 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	194
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	195 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	196
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	197
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	198 <section name="Error handling" id="error_handling">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	199
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	200 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	201 The <literal>ngx_errno</literal> macro returns the last system error code.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	202 It's mapped to <literal>errno</literal> on POSIX platforms and to
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	203 <literal>GetLastError()</literal> call in Windows.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	204 The <literal>ngx_socket_errno</literal> macro returns the last socket error
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	205 number.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	206 Like the <literal>ngx_errno</literal> macro, it's mapped to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	207 <literal>errno</literal> on POSIX platforms.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	208 It's mapped to the <literal>WSAGetLastError()</literal> call on Windows.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	209 Accessing the values of <literal>ngx_errno</literal> or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	210 <literal>ngx_socket_errno</literal> more than once in a row can cause
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	211 performance issues.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	212 If the error value might be used multiple times, store it in a local variable
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	213 of type <literal>ngx_err_t</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	214 To set errors, use the <literal>ngx_set_errno(errno)</literal> and
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	215 <literal>ngx_set_socket_errno(errno)</literal> macros.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	216 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	217
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	218 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	219 The values of <literal>ngx_errno</literal> and
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	220 <literal>ngx_socket_errno</literal> can be passed to the logging functions
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	221 <literal>ngx_log_error()</literal> and <literal>ngx_log_debugX()</literal>, in
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	222 which case system error text is added to the log message.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	223 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	224
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	225 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	226 Example using <literal>ngx_errno</literal>:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	227 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	228
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	229
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	230 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	231 void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	232 ngx_my_kill(ngx_pid_t pid, ngx_log_t *log, int signo)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	233 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	234 ngx_err_t err;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	235
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	236 if (kill(pid, signo) == -1) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	237 err = ngx_errno;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	238
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	239 ngx_log_error(NGX_LOG_ALERT, log, err, "kill(%P, %d) failed", pid, signo);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	240
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	241 if (err == NGX_ESRCH) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	242 return 2;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	243 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	244
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	245 return 1;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	246 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	247
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	248 return 0;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	249 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	250 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	251
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	252 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	253
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	254
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	255 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	256
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	257
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	258 <section name="Strings" id="strings">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	259
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	260
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	261 <section name="Overview" id="overview">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	262
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	263 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	264 For C strings, nginx uses the unsigned character type pointer
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	265 <literal>u_char *</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	266 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	267
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	268 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	269 The nginx string type <literal>ngx_str_t</literal> is defined as follows:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	270 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	271
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	272
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	273 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	274 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	275 size_t len;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	276 u_char *data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	277 } ngx_str_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	278 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	279
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	280 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	281 The <literal>len</literal> field holds the string length and
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	282 <literal>data</literal> holds the string data.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	283 The string, held in <literal>ngx_str_t</literal>, may or may not be
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	284 null-terminated after the <literal>len</literal> bytes.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	285 In most cases it’s not.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	286 However, in certain parts of the code (for example, when parsing configuration),
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	287 <literal>ngx_str_t</literal> objects are known to be null-terminated, which
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	288 simplifies string comparison and makes it easier to pass the strings to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	289 syscalls.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	290 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	291
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	292 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	293 The string operations in nginx are declared in
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	294 <path>src/core/ngx_string.h</path>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	295 Some of them are wrappers around standard C functions:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	296 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	297
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	298 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	299 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	300
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	301 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	302 <literal>ngx_strcmp()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	303 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	304
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	305 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	306 <literal>ngx_strncmp()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	307 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	308
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	309 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	310 <literal>ngx_strstr()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	311 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	312
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	313 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	314 <literal>ngx_strlen()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	315 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	316
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	317 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	318 <literal>ngx_strchr()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	319 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	320
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	321 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	322 <literal>ngx_memcmp()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	323 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	324
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	325 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	326 <literal>ngx_memset()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	327 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	328
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	329 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	330 <literal>ngx_memcpy()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	331 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	332
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	333 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	334 <literal>ngx_memmove()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	335 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	336
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	337 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	338
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	339 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	340
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	341 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	342 Other string functions are nginx-specific
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	343 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	344
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	345 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	346 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	347
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	348 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	349 <literal>ngx_memzero()</literal> — Fills memory with zeroes.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	350 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	351
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	352 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	353 <literal>ngx_cpymem()</literal> — Does the same as
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	354 <literal>ngx_memcpy()</literal>, but returns the final destination address
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	355 This one is handy for appending multiple strings in a row.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	356 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	357
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	358 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	359 <literal>ngx_movemem()</literal> — Does the same as
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	360 <literal>ngx_memmove()</literal>, but returns the final destination address.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	361 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	362
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	363 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	364 <literal>ngx_strlchr()</literal> — Searches for a character in a string,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	365 delimited by two pointers.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	366 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	367 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	368 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	369
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	370 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	371 The following functions perform case conversion and comparison:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	372 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	373
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	374 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	375 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	376
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	377 <listitem>
1999 1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	378 <literal>ngx_tolower()</literal>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	379 </listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	380
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	381 <listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	382 <literal>ngx_toupper()</literal>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	383 </listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	384
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	385 <listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	386 <literal>ngx_strlow()</literal>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	387 </listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	388
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	389 <listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	390 <literal>ngx_strcasecmp()</literal>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	391 </listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	392
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	393 <listitem>
1b086de6a05b DevGuide: style. Roman Arutyunyan <arut@nginx.com> parents: 1998 diff changeset	394 <literal>ngx_strncasecmp()</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	395 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	396
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	397 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	398 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	399
1998 18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	400 <para>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	401 The following macros simplify string initialization:
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	402 </para>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	403
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	404 <list type="bullet">
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	405
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	406 <listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	407 <literal>ngx_string(text)</literal> — static initializer for the
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	408 <literal>ngx_str_t</literal> type from the C string literal
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	409 <literal>text</literal>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	410 </listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	411
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	412 <listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	413 <literal>ngx_null_string</literal> — static empty string initializer for the
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	414 <literal>ngx_str_t</literal> type
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	415 </listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	416
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	417 <listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	418 <literal>ngx_str_set(str, text)</literal> — initializes string
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	419 <literal>str</literal> of <literal>ngx_str_t *</literal> type with the C string
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	420 literal <literal>text</literal>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	421 </listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	422
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	423 <listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	424 <literal>ngx_str_null(str)</literal> — initializes string <literal>str</literal>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	425 of <literal>ngx_str_t *</literal> type with the empty string
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	426 </listitem>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	427
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	428 </list>
18404f5a5600 DevGuide: string initialization macros. Roman Arutyunyan <arut@nginx.com> parents: 1997 diff changeset	429
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	430 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	431
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	432
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	433 <section name="Formatting" id="formatting">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	434
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	435 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	436 The following formatting functions support nginx-specific types:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	437 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	438
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	439
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	440 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	441 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	442
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	443 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	444 <literal>ngx_sprintf(buf, fmt, ...)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	445 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	446
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	447 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	448 <literal>ngx_snprintf(buf, max, fmt, ...)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	449 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	450
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	451 <listitem>
1975 459a6f194fcf Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1971 diff changeset	452 <literal>ngx_slprintf(buf, last, fmt, ...)</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	453 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	454
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	455 <listitem>
2079 05f5bfdaffa3 Development guide: fixed formatting function names. Maxim Dounin <mdounin@mdounin.ru> parents: 2078 diff changeset	456 <literal>ngx_vslprintf(buf, last, fmt, args)</literal>
05f5bfdaffa3 Development guide: fixed formatting function names. Maxim Dounin <mdounin@mdounin.ru> parents: 2078 diff changeset	457 </listitem>
05f5bfdaffa3 Development guide: fixed formatting function names. Maxim Dounin <mdounin@mdounin.ru> parents: 2078 diff changeset	458
05f5bfdaffa3 Development guide: fixed formatting function names. Maxim Dounin <mdounin@mdounin.ru> parents: 2078 diff changeset	459 <listitem>
05f5bfdaffa3 Development guide: fixed formatting function names. Maxim Dounin <mdounin@mdounin.ru> parents: 2078 diff changeset	460 <literal>ngx_vsnprintf(buf, max, fmt, args)</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	461 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	462
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	463 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	464 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	465
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	466 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	467 The full list of formatting options, supported by these functions is
1915 8b7c3b0ef1a4 Semantically marked paths. Vladimir Homutov <vl@nginx.com> parents: 1914 diff changeset	468 in <path>src/core/ngx_string.c</path>. Some of them are:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	469 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	470
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	471
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	472 <list type="bullet">
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	473
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	474 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	475 <literal>%O</literal> — <literal>off_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	476 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	477
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	478 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	479 <literal>%T</literal> — <literal>time_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	480 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	481
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	482 <listitem>
1997 eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	483 <literal>%z</literal> — <literal>ssize_t</literal>
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	484 </listitem>
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	485
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	486 <listitem>
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	487 <literal>%i</literal> — <literal>ngx_int_t</literal>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	488 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	489
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	490 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	491 <literal>%p</literal> — <literal>void *</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	492 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	493
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	494 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	495 <literal>%V</literal> — <literal>ngx_str_t *</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	496 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	497
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	498 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	499 <literal>%s</literal> — <literal>u_char *</literal> (null-terminated)
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	500 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	501
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	502 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	503 <literal>%s</literal> — <literal>size_t + u_char </literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	504 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	505
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	506 </list>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	507
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	508
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	509 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	510 You can prepend <literal>u</literal> on most types to make them unsigned.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	511 To convert output to hex, use <literal>X</literal> or <literal>x</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	512 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	513
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	514 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	515 For example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	516
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	517 <programlisting>
1997 eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	518 u_char buf[NGX_INT_T_LEN];
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	519 size_t len;
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	520 ngx_uint_t n;
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	521
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	522 /* set n here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	523
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	524 len = ngx_sprintf(buf, "%ui", n) — buf;
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	525 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	526
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	527 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	528
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	529 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	530
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	531
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	532 <section name="Numeric conversion" id="numeric_conversion">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	533
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	534 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	535 Several functions for numeric conversion are implemented in nginx.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	536 The first four each convert a string of given length to a positive integer of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	537 the indicated type.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	538 They return <literal>NGX_ERROR</literal> on error.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	539
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	540 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	541
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	542 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	543 <literal>ngx_atoi(line, n)</literal> — <literal>ngx_int_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	544 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	545
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	546 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	547 <literal>ngx_atosz(line, n)</literal> — <literal>ssize_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	548 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	549
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	550 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	551 <literal>ngx_atoof(line, n)</literal> — <literal>off_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	552 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	553
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	554 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	555 <literal>ngx_atotm(line, n)</literal> — <literal>time_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	556 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	557
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	558 </list>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	559 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	560
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	561 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	562 There are two additional numeric conversion functions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	563 Like the first four, they return <literal>NGX_ERROR</literal> on error.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	564
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	565 <list type="bullet">
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	566
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	567 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	568 <literal>ngx_atofp(line, n, point)</literal> — Converts a fixed point floating
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	569 number of given length to a positive integer of type
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	570 <literal>ngx_int_t</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	571 The result is shifted left by <literal>point</literal> decimal
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	572 positions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	573 The string representation of the number is expected to have no more
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	574 than <literal>points</literal> fractional digits.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	575 For example, <literal>ngx_atofp("10.5", 4, 2)</literal> returns
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	576 <literal>1050</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	577 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	578
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	579 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	580 <literal>ngx_hextoi(line, n)</literal> — Converts a hexadecimal representation
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	581 of a positive integer to <literal>ngx_int_t</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	582 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	583
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	584 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	585 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	586
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	587 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	588
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	589 <section name="Regular expressions" id="regex">
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	590
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	591 <para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	592 The regular expressions interface in nginx is a wrapper around
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	593 the <link url="http://www.pcre.org">PCRE</link>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	594 library.
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	595 The corresponding header file is <path>src/core/ngx_regex.h</path>.
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	596 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	597
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	598 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	599 To use a regular expression for string matching, it first needs to be
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	600 compiled, which is usually done at the configuration phase.
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	601 Note that since PCRE support is optional, all code using the interface must
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	602 be protected by the surrounding <literal>NGX_PCRE</literal> macro:
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	603
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	604 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	605 #if (NGX_PCRE)
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	606 ngx_regex_t *re;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	607 ngx_regex_compile_t rc;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	608
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	609 u_char errstr[NGX_MAX_CONF_ERRSTR];
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	610
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	611 ngx_str_t value = ngx_string("message (\\d\\d\\d).*Codeword is '(?<cw>\\w+)'");
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	612
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	613 ngx_memzero(&rc, sizeof(ngx_regex_compile_t));
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	614
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	615 rc.pattern = value;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	616 rc.pool = cf->pool;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	617 rc.err.len = NGX_MAX_CONF_ERRSTR;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	618 rc.err.data = errstr;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	619 /* rc.options are passed as is to pcre_compile() */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	620
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	621 if (ngx_regex_compile(&rc) != NGX_OK) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	622 ngx_conf_log_error(NGX_LOG_EMERG, cf, 0, "%V", &rc.err);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	623 return NGX_CONF_ERROR;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	624 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	625
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	626 re = rc.regex;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	627 #endif
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	628 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	629 After successful compilation, the <literal>captures</literal> and
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	630 <literal>named_captures</literal> fields in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	631 <literal>ngx_regex_compile_t</literal> structure contain the count of all
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	632 captures and named captures, respectively, found in the regular expression.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	633 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	634
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	635 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	636 The compiled regular expression can then be used for matching against strings:
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	637 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	638 ngx_int_t n;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	639 int captures[(1 + rc.captures) * 3];
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	640
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	641 ngx_str_t input = ngx_string("This is message 123. Codeword is 'foobar'.");
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	642
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	643 n = ngx_regex_exec(re, &input, captures, (1 + rc.captures) * 3);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	644 if (n >= 0) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	645 /* string matches expression */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	646
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	647 } else if (n == NGX_REGEX_NO_MATCHED) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	648 /* no match was found */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	649
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	650 } else {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	651 /* some error */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	652 ngx_log_error(NGX_LOG_ALERT, log, 0, ngx_regex_exec_n " failed: %i", n);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	653 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	654 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	655 The arguments to <literal>ngx_regex_exec()</literal> are the compiled regular
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	656 expression <literal>re</literal>, the string to match <literal>s</literal>,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	657 an optional array of integers to hold any <literal>captures</literal> that are
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	658 found, and the array's <literal>size</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	659 The size of the <literal>captures</literal> array must be a multiple of three,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	660 as required by the
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	661 <link url="http://www.pcre.org/original/doc/html/pcreapi.html">PCRE API</link>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	662 In the example, the size is calculated from the total number of captures plus
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	663 <literal>1</literal>one for the matched string itself.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	664 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	665
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	666 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	667 If there are matches, captures can be accessed as follows:
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	668 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	669 u_char *p;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	670 size_t size;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	671 ngx_str_t name, value;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	672
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	673 /* all captures */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	674 for (i = 0; i < n * 2; i += 2) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	675 value.data = input.data + captures[i];
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	676 value.len = captures[i + 1] — captures[i];
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	677 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	678
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	679 /* accessing named captures */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	680
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	681 size = rc.name_size;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	682 p = rc.names;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	683
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	684 for (i = 0; i < rc.named_captures; i++, p += size) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	685
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	686 /* capture name */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	687 name.data = &p[2];
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	688 name.len = ngx_strlen(name.data);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	689
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	690 n = 2 * ((p[0] << 8) + p[1]);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	691
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	692 /* captured value */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	693 value.data = &input.data[captures[n]];
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	694 value.len = captures[n + 1] — captures[n];
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	695 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	696 </programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	697 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	698
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	699 <para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	700 The <literal>ngx_regex_exec_array()</literal> function accepts the array of
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	701 <literal>ngx_regex_elt_t</literal> elements (which are just compiled regular
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	702 expressions with associated names), a string to match, and a log.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	703 The function applies expressions from the array to the string until
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	704 either a match is found or no more expressions are left.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	705 The return value is <literal>NGX_OK</literal> when there is a match and
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	706 <literal>NGX_DECLINED</literal> otherwise, or <literal>NGX_ERROR</literal>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	707 in case of error.
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	708 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	709
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	710 </section>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	711
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	712 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	713
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	714
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	715 <section name="Time" id="time">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	716
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	717 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	718 The <literal>ngx_time_t</literal> structure represents time with three separate
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	719 types for seconds, milliseconds, and the GMT offset:
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	720 <programlisting>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	721 typedef struct {
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	722 time_t sec;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	723 ngx_uint_t msec;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	724 ngx_int_t gmtoff;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	725 } ngx_time_t;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	726 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	727 The <literal>ngx_tm_t</literal> structure is an alias for
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	728 <literal>struct tm</literal> on UNIX platforms and <literal>SYSTEMTIME</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	729 on Windows.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	730 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	731
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	732 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	733 To obtain the current time, it is usually sufficient to access one of the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	734 available global variables, representing the cached time value in the desired
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	735 format.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	736 For example, the <literal>ngx_current_msec</literal> variable holds the number
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	737 of milliseconds elapsed since Epoch and truncated to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	738 <literal>ngx_msec_t</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	739 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	740
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	741 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	742 The available string representations are:
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	743
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	744 <list type="bullet">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	745
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	746 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	747 <literal>ngx_cached_err_log_time</literal> — Used in error log entries:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	748 <literal>"1970/09/28 12:00:00"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	749 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	750
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	751 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	752 <literal>ngx_cached_http_log_time</literal> — Used in HTTP access log entries:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	753 <literal>"28/Sep/1970:12:00:00 +0600"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	754 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	755
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	756 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	757 <literal>ngx_cached_syslog_time</literal> — Used in syslog entries:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	758 <literal>"Sep 28 12:00:00"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	759 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	760
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	761 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	762 <literal>ngx_cached_http_time</literal> — Used in HTTP headers:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	763 <literal>"Mon, 28 Sep 1970 06:00:00 GMT"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	764 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	765
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	766 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	767 <literal>ngx_cached_http_log_iso8601</literal> — The ISO 8601
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	768 standard format:
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	769 <literal>"1970-09-28T12:00:00+06:00"</literal>
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	770 </listitem>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	771
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	772 </list>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	773 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	774
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	775 <para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	776 The <literal>ngx_time()</literal> and <literal>ngx_timeofday()</literal> macros
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	777 return the current time value in seconds and are the preferred way to access
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	778 the cached time value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	779 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	780
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	781 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	782 To obtain the time explicitly, use <literal>ngx_gettimeofday()</literal>,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	783 which updates its argument (pointer to
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	784 <literal>struct timeval</literal>).
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	785 The time is always updated when nginx returns to the event loop from system
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	786 calls.
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	787 To update the time immediately, call <literal>ngx_time_update()</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	788 or <literal>ngx_time_sigsafe_update()</literal> if updating the time in the
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	789 signal handler context.
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	790 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	791
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	792 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	793 The following functions convert <literal>time_t</literal> into the indicated
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	794 broken-down time representation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	795 The first function in each pair converts <literal>time_t</literal> to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	796 <literal>ngx_tm_t</literal> and the second (with the <literal>_libc_</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	797 infix) to <literal>struct tm</literal>:
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	798
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	799 <list type="bullet">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	800
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	801 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	802 <literal>ngx_gmtime(), ngx_libc_gmtime()</literal> — Time expressed as UTC
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	803 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	804
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	805 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	806 <literal>ngx_localtime(), ngx_libc_localtime()</literal> — Time expressed
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	807 relative to the local time zone
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	808 </listitem>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	809
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	810 </list>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	811
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	812 The <literal>ngx_http_time(buf, time)</literal> function returns a string
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	813 representation suitable for use in HTTP headers (for example,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	814 <literal>"Mon, 28 Sep 1970 06:00:00 GMT"</literal>).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	815 The <literal>ngx_http_cookie_time(buf, time)</literal> returns a string
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	816 representation function returns a string representation suitable
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	817 for HTTP cookies (<literal>"Thu, 31-Dec-37 23:55:55 GMT"</literal>).
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	818 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	819
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	820 </section>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	821
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	822
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	823 <section name="Containers" id="containers">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	824
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	825
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	826 <section name="Array" id="array">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	827
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	828 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	829 The nginx array type <literal>ngx_array_t</literal> is defined as follows
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	830 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	831
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	832
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	833 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	834 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	835 void *elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	836 ngx_uint_t nelts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	837 size_t size;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	838 ngx_uint_t nalloc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	839 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	840 } ngx_array_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	841 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	842
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	843 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	844 The elements of the array are available in the <literal>elts</literal> field.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	845 The <literal>nelts</literal> field holds the number of elements.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	846 The <literal>size</literal> field holds the size of a single element and is set
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	847 when the array is initialized.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	848 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	849
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	850 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	851 Use the <literal>ngx_array_create(pool, n, size)</literal> call to create an
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	852 array in a pool, and the <literal>ngx_array_init(array, pool, n, size)</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	853 call to initialize an array object that has already been allocated.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	854 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	855
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	856
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	857 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	858 ngx_array_t *a, b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	859
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	860 /* create an array of strings with preallocated memory for 10 elements */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	861 a = ngx_array_create(pool, 10, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	862
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	863 /* initialize string array for 10 elements */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	864 ngx_array_init(&b, pool, 10, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	865 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	866
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	867 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	868 Use the following functions to add elements to an array:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	869 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	870
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	871 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	872 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	873
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	874 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	875 <literal>ngx_array_push(a)</literal> adds one tail element and returns pointer
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	876 to it
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	877 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	878
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	879 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	880 <literal>ngx_array_push_n(a, n)</literal> adds <literal>n</literal> tail elements
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	881 and returns pointer to the first one
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	882 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	883
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	884 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	885 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	886
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	887 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	888 If the currently allocated amount of memory is not large enough to accommodate
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	889 the new elements, a new block of memory is allocated and the existing elements
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	890 are copied to it.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	891 The new memory block is normally twice as large as the existing one.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	892 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	893
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	894
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	895 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	896 s = ngx_array_push(a);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	897 ss = ngx_array_push_n(&b, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	898 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	899
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	900 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	901
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	902
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	903 <section name="List" id="list">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	904
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	905 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	906 In nginx a list is a sequence of arrays, optimized for inserting a potentially
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	907 large number of items.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	908 The <literal>ngx_list_t</literal> list type is defined as follows:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	909 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	910
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	911
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	912 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	913 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	914 ngx_list_part_t *last;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	915 ngx_list_part_t part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	916 size_t size;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	917 ngx_uint_t nalloc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	918 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	919 } ngx_list_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	920 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	921
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	922 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	923 The actual items are stored in list parts, which are defined as follows:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	924 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	925
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	926
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	927 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	928 typedef struct ngx_list_part_s ngx_list_part_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	929
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	930 struct ngx_list_part_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	931 void *elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	932 ngx_uint_t nelts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	933 ngx_list_part_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	934 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	935 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	936
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	937 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	938 Before use, a list must be initialized by calling
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	939 <literal>ngx_list_init(list, pool, n, size)</literal> or created by calling
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	940 <literal>ngx_list_create(pool, n, size)</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	941 Both functions take as arguments the size of a single item and a number of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	942 items per list part.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	943 To add an item to a list, use the <literal>ngx_list_push(list)</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	944 function.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	945 To iterate over the items, directly access the list fields as shown in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	946 example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	947 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	948
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	949
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	950 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	951 ngx_str_t *v;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	952 ngx_uint_t i;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	953 ngx_list_t *list;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	954 ngx_list_part_t *part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	955
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	956 list = ngx_list_create(pool, 100, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	957 if (list == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	958
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	959 /* add items to the list */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	960
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	961 v = ngx_list_push(list);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	962 if (v == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	963 ngx_str_set(v, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	964
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	965 v = ngx_list_push(list);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	966 if (v == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	967 ngx_str_set(v, "bar");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	968
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	969 /* iterate over the list */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	970
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	971 part = &list->part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	972 v = part->elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	973
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	974 for (i = 0; /* void */; i++) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	975
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	976 if (i >= part->nelts) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	977 if (part->next == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	978 break;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	979 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	980
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	981 part = part->next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	982 v = part->elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	983 i = 0;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	984 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	985
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	986 ngx_do_smth(&v[i]);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	987 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	988 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	989
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	990 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	991 Lists are primarily used for HTTP input and output headers.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	992 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	993
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	994 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	995 Lists do not support item removal.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	996 However, when needed, items can internally be marked as missing without actually
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	997 being removed from the list.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	998 For example, to mark HTTP output headers (which are stored as
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	999 <literal>ngx_table_elt_t</literal> objects) as missing, set the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1000 <literal>hash</literal> field in <literal>ngx_table_elt_t</literal> to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1001 zero.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1002 Items marked in this way are explicitly skipped when the headers are iterated
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1003 over.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1004 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1005
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1006 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1007
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1008
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1009 <section name="Queue" id="queue">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1010
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1011 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1012 In nginx a queue is an intrusive doubly linked list, with each node defined as
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1013 follows:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1014 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1015
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1016
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1017 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1018 typedef struct ngx_queue_s ngx_queue_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1019
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1020 struct ngx_queue_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1021 ngx_queue_t *prev;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1022 ngx_queue_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1023 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1024 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1025
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1026 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1027 The head queue node is not linked with any data.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1028 Use the <literal>ngx_queue_init(q)</literal> call to initialize the list head
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1029 before use.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1030 Queues support the following operations:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1031 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1032
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1033 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1034 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1035
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1036 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1037 <literal>ngx_queue_insert_head(h, x)</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1038 <literal>ngx_queue_insert_tail(h, x)</literal> — Insert a new node
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1039 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1040
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1041 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1042 <literal>ngx_queue_remove(x)</literal> — Remove a queue node
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1043 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1044
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1045 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1046 <literal>ngx_queue_split(h, q, n)</literal> — Split a queue at a node,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1047 returning the queue tail in a separate queue
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1048 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1049
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1050 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1051 <literal>ngx_queue_add(h, n)</literal> — Add a second queue to the first queue
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1052 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1053
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1054 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1055 <literal>ngx_queue_head(h)</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1056 <literal>ngx_queue_last(h)</literal> — Get first or last queue node
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1057 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1058
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1059 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1060 <literal>ngx_queue_sentinel(h)</literal> - Get a queue sentinel object to end
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1061 iteration at
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1062 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1063
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1064 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1065 <literal>ngx_queue_data(q, type, link)</literal> — Get a reference to the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1066 beginning of a queue node data structure, considering the queue field offset in
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1067 it
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1068 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1069
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1070 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1071 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1072
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1073 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1074 An example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1075 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1076
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1077
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1078 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1079 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1080 ngx_str_t value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1081 ngx_queue_t queue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1082 } ngx_foo_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1083
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1084 ngx_foo_t *f;
2008 1f2f9fa97065 DevGuide: fixed queue example. Vladimir Homutov <vl@nginx.com> parents: 2007 diff changeset	1085 ngx_queue_t values, *q;
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1086
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1087 ngx_queue_init(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1088
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1089 f = ngx_palloc(pool, sizeof(ngx_foo_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1090 if (f == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1091 ngx_str_set(&f->value, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1092
2008 1f2f9fa97065 DevGuide: fixed queue example. Vladimir Homutov <vl@nginx.com> parents: 2007 diff changeset	1093 ngx_queue_insert_tail(&values, &f->queue);
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1094
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1095 /* insert more nodes here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1096
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1097 for (q = ngx_queue_head(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1098 q != ngx_queue_sentinel(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1099 q = ngx_queue_next(q))
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1100 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1101 f = ngx_queue_data(q, ngx_foo_t, queue);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1102
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1103 ngx_do_smth(&f->value);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1104 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1105 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1106
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1107 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1108
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1109
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1110 <section name="Red-Black tree" id="red_black_tree">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1111
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1112 <para>
1915 8b7c3b0ef1a4 Semantically marked paths. Vladimir Homutov <vl@nginx.com> parents: 1914 diff changeset	1113 The <path>src/core/ngx_rbtree.h</path> header file provides access to the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1114 effective implementation of red-black trees.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1115 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1116
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1117
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1118 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1119 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1120 ngx_rbtree_t rbtree;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1121 ngx_rbtree_node_t sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1122
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1123 /* custom per-tree data here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1124 } my_tree_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1125
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1126 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1127 ngx_rbtree_node_t rbnode;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1128
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1129 /* custom per-node data */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1130 foo_t val;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1131 } my_node_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1132 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1133
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1134 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1135 To deal with a tree as a whole, you need two nodes: root and sentinel.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1136 Typically, they are added to a custom structure, allowing you to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1137 organize your data into a tree in which the leaves contain a link to or embed
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1138 your data.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1139 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1140
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1141 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1142 To initialize a tree:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1143 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1144
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1145
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1146 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1147 my_tree_t root;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1148
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1149 ngx_rbtree_init(&root.rbtree, &root.sentinel, insert_value_function);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1150 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1151
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1152 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1153 To traverse a tree and insert new values, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1154 "<literal>insert_value</literal>" functions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1155 For example, the <literal>ngx_str_rbtree_insert_value</literal> function deals
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1156 with the <literal>ngx_str_t</literal> type.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1157 Its arguments are pointers to a root node of an insertion, the newly created
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1158 node to be added, and a tree sentinel.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1159 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1160
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1161
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1162 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1163 void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1164 ngx_rbtree_node_t *node,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1165 ngx_rbtree_node_t *sentinel)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1166 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1167
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1168
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1169 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1170 The traversal is pretty straightforward and can be demonstrated with the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1171 following lookup function pattern:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1172 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1173
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1174
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1175 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1176 my_node_t *
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1177 my_rbtree_lookup(ngx_rbtree_t rbtree, foo_t val, uint32_t hash)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1178 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1179 ngx_int_t rc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1180 my_node_t *n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1181 ngx_rbtree_node_t node, sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1182
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1183 node = rbtree->root;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1184 sentinel = rbtree->sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1185
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1186 while (node != sentinel) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1187
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1188 n = (my_node_t *) node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1189
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1190 if (hash != node->key) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1191 node = (hash < node->key) ? node->left : node->right;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1192 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1193 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1194
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1195 rc = compare(val, node->val);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1196
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1197 if (rc < 0) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1198 node = node->left;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1199 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1200 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1201
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1202 if (rc > 0) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1203 node = node->right;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1204 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1205 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1206
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1207 return n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1208 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1209
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1210 return NULL;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1211 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1212 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1213
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1214 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1215 The <literal>compare()</literal> function is a classic comparator function that
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1216 returns a value less than, equal to, or greater than zero.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1217 To speed up lookups and avoid comparing user objects that can be big, an integer
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1218 hash field is used.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1219 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1220
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1221 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1222 To add a node to a tree, allocate a new node, initialize it and call
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1223 <literal>ngx_rbtree_insert()</literal>:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1224 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1225
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1226
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1227 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1228 my_node_t *my_node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1229 ngx_rbtree_node_t *node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1230
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1231 my_node = ngx_palloc(...);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1232 init_custom_data(&my_node->val);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1233
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1234 node = &my_node->rbnode;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1235 node->key = create_key(my_node->val);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1236
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1237 ngx_rbtree_insert(&root->rbtree, node);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1238 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1239
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1240 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1241 To remove a node, call the <literal>ngx_rbtree_delete()</literal> function:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1242 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1243
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1244
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1245 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1246 ngx_rbtree_delete(&root->rbtree, node);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1247 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1248
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1249 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1250
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1251 <section name="Hash" id="hash">
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1252
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1253 <para>
1920 de5251816480 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1919 diff changeset	1254 Hash table functions are declared in <path>src/core/ngx_hash.h</path>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1255 Both exact and wildcard matching are supported.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1256 The latter requires extra setup and is described in a separate section below.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1257 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1258
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1259 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1260 Before initializing a hash, you need to know the number of elements it will
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1261 hold so that nginx can build it optimally.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1262 Two parameters that need to be configured are <literal>max_size</literal>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1263 and <literal>bucket_size</literal>, as detailed in a separate
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1264 <link doc="../hash.xml">document</link>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1265 They are usually configurable by the user.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1266 Hash initialization settings are stored with the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1267 <literal>ngx_hash_init_t</literal> type, and the hash itself is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1268 <literal>ngx_hash_t</literal>:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1269 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1270 ngx_hash_t foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1271 ngx_hash_init_t hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1272
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1273 hash.hash = &foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1274 hash.key = ngx_hash_key;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1275 hash.max_size = 512;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1276 hash.bucket_size = ngx_align(64, ngx_cacheline_size);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1277 hash.name = "foo_hash";
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1278 hash.pool = cf->pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1279 hash.temp_pool = cf->temp_pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1280 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1281 The <literal>key</literal> is a pointer to a function that creates the hash
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1282 integer key from a string.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1283 There are two generic key-creation functions:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1284 <literal>ngx_hash_key(data, len)</literal> and
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1285 <literal>ngx_hash_key_lc(data, len)</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1286 The latter converts a string to all lowercase characters, so the passed string
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1287 must be writeable.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1288 If that is not true, pass the <literal>NGX_HASH_READONLY_KEY</literal> flag
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1289 to the function, initializing the key array (see below).
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1290 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1291
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1292 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1293 The hash keys are stored in <literal>ngx_hash_keys_arrays_t</literal> and
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1294 are initialized with <literal>ngx_hash_keys_array_init(arr, type)</literal>:
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1295 The second parameter (<literal>type</literal>) controls the amount of resources
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1296 preallocated for the hash and can be either <literal>NGX_HASH_SMALL</literal> or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1297 <literal>NGX_HASH_LARGE</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1298 The latter is appropriate if you expect the hash to contain thousands of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1299 elements.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1300
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1301 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1302 ngx_hash_keys_arrays_t foo_keys;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1303
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1304 foo_keys.pool = cf->pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1305 foo_keys.temp_pool = cf->temp_pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1306
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1307 ngx_hash_keys_array_init(&foo_keys, NGX_HASH_SMALL);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1308 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1309 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1310
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1311 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1312 To insert keys into a hash keys array, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1313 <literal>ngx_hash_add_key(keys_array, key, value, flags)</literal> function:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1314 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1315 ngx_str_t k1 = ngx_string("key1");
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1316 ngx_str_t k2 = ngx_string("key2");
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1317
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1318 ngx_hash_add_key(&foo_keys, &k1, &my_data_ptr_1, NGX_HASH_READONLY_KEY);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1319 ngx_hash_add_key(&foo_keys, &k2, &my_data_ptr_2, NGX_HASH_READONLY_KEY);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1320 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1321 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1322
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1323 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1324 To build the hash table, call the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1325 <literal>ngx_hash_init(hinit, key_names, nelts)</literal> function:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1326
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1327 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1328 ngx_hash_init(&hash, foo_keys.keys.elts, foo_keys.keys.nelts);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1329 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1330
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1331 The function fails if <literal>max_size</literal> or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1332 <literal>bucket_size</literal> parameters are not big enough.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1333 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1334
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1335 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1336 When the hash is built, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1337 <literal>ngx_hash_find(hash, key, name, len)</literal> function to look up
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1338 elements:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1339 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1340 my_data_t *data;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1341 ngx_uint_t key;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1342
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1343 key = ngx_hash_key(k1.data, k1.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1344
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1345 data = ngx_hash_find(&foo_hash, key, k1.data, k1.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1346 if (data == NULL) {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1347 /* key not found */
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1348 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1349 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1350
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1351 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1352
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1353 <section name="Wildcard matching" id="wildcard_matching">
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1354
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1355 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1356 To create a hash that works with wildcards, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1357 <literal>ngx_hash_combined_t</literal> type.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1358 It includes the hash type described above and has two additional keys arrays:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1359 <literal>dns_wc_head</literal> and <literal>dns_wc_tail</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1360 The initialization of basic properties is similar to a regular hash:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1361 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1362 ngx_hash_init_t hash
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1363 ngx_hash_combined_t foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1364
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1365 hash.hash = &foo_hash.hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1366 hash.key = ...;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1367 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1368 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1369
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1370 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1371 It is possible to add wildcard keys using the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1372 <literal>NGX_HASH_WILDCARD_KEY</literal> flag:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1373 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1374 /* k1 = ".example.org"; */
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1375 /* k2 = "foo."; /
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1376 ngx_hash_add_key(&foo_keys, &k1, &data1, NGX_HASH_WILDCARD_KEY);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1377 ngx_hash_add_key(&foo_keys, &k2, &data2, NGX_HASH_WILDCARD_KEY);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1378 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1379 The function recognizes wildcards and adds keys into the corresponding arrays.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1380 Please refer to the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1381 <link doc="../http/ngx_http_map_module.xml" id="map"/> module
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1382 documentation for the description of the wildcard syntax and the
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1383 matching algorithm.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1384 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1385
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1386 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1387 Depending on the contents of added keys, you may need to initialize up to three
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1388 key arrays: one for exact matching (described above), and two more to enable
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1389 matching starting from the head or tail of a string:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1390 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1391 if (foo_keys.dns_wc_head.nelts) {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1392
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1393 ngx_qsort(foo_keys.dns_wc_head.elts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1394 (size_t) foo_keys.dns_wc_head.nelts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1395 sizeof(ngx_hash_key_t),
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1396 cmp_dns_wildcards);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1397
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1398 hash.hash = NULL;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1399 hash.temp_pool = pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1400
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1401 if (ngx_hash_wildcard_init(&hash, foo_keys.dns_wc_head.elts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1402 foo_keys.dns_wc_head.nelts)
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1403 != NGX_OK)
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1404 {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1405 return NGX_ERROR;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1406 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1407
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1408 foo_hash.wc_head = (ngx_hash_wildcard_t *) hash.hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1409 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1410 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1411 The keys array needs to be sorted, and initialization results must be added
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1412 to the combined hash.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1413 The initialization of <literal>dns_wc_tail</literal> array is done similarly.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1414 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1415
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1416 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1417 The lookup in a combined hash is handled by the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1418 <literal>ngx_hash_find_combined(chash, key, name, len)</literal>:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1419 <programlisting>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	1420 /* key = "bar.example.org"; — will match ".example.org" */
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	1421 /* key = "foo.example.com"; — will match "foo." /
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1422
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1423 hkey = ngx_hash_key(key.data, key.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1424 res = ngx_hash_find_combined(&foo_hash, hkey, key.data, key.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1425 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1426 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1427
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1428 </section>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1429
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1430 </section>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1431
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1432 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1433
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1434
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1435 <section name="Memory management" id="memory_management">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1436
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1437
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1438 <section name="Heap" id="heap">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1439
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1440 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1441 To allocate memory from system heap, use the following functions:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1442 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1443
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1444 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1445 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1446
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1447 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1448 <literal>ngx_alloc(size, log)</literal> — Allocate memory from system heap.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1449 This is a wrapper around <literal>malloc()</literal> with logging support.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1450 Allocation error and debugging information is logged to <literal>log</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1451 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1452
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1453 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1454 <literal>ngx_calloc(size, log)</literal> — Allocate memory from system heap
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1455 like <literal>ngx_alloc()</literal>, but fill memory with zeros after
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1456 allocation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1457 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1458
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1459 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1460 <literal>ngx_memalign(alignment, size, log)</literal> — Allocate aligned memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1461 from system heap.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1462 This is a wrapper around <literal>posix_memalign()</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1463 on those platforms that provide that function.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1464 Otherwise implementation falls back to <literal>ngx_alloc()</literal> which
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1465 provides maximum alignment.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1466 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1467
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1468 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1469 <literal>ngx_free(p)</literal> — Free allocated memory.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1470 This is a wrapper around <literal>free()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1471 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1472
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1473 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1474 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1475
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1476 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1477
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1478
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1479 <section name="Pool" id="pool">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1480
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1481 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1482 Most nginx allocations are done in pools.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1483 Memory allocated in an nginx pool is freed automatically when the pool is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1484 destroyed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1485 This provides good allocation performance and makes memory control easy.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1486 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1487
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1488 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1489 A pool internally allocates objects in continuous blocks of memory.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1490 Once a block is full, a new one is allocated and added to the pool memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1491 block list.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1492 When the requested allocation is too large to fit into a block, the request
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1493 is forwarded to the system allocator and the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1494 returned pointer is stored in the pool for further deallocation.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1495 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1496
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1497 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1498 The type for nginx pools is <literal>ngx_pool_t</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1499 The following operations are supported:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1500 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1501
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1502 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1503 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1504
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1505 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1506 <literal>ngx_create_pool(size, log)</literal> — Create a pool with specified
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1507 block size.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1508 The pool object returned is allocated in the pool as well.
2081 f29bd40e9a62 Development guide: documented ngx_create_pool() size requirements. Ruslan Ermilov <ru@nginx.com> parents: 2079 diff changeset	1509 The <literal>size</literal>
f29bd40e9a62 Development guide: documented ngx_create_pool() size requirements. Ruslan Ermilov <ru@nginx.com> parents: 2079 diff changeset	1510 should be at least <literal>NGX_MIN_POOL_SIZE</literal>
f29bd40e9a62 Development guide: documented ngx_create_pool() size requirements. Ruslan Ermilov <ru@nginx.com> parents: 2079 diff changeset	1511 and a multiple of <literal>NGX_POOL_ALIGNMENT</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1512 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1513
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1514 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1515 <literal>ngx_destroy_pool(pool)</literal> — Free all pool memory, including
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1516 the pool object itself.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1517 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1518
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1519 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1520 <literal>ngx_palloc(pool, size)</literal> — Allocate aligned memory from the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1521 specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1522 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1523
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1524 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1525 <literal>ngx_pcalloc(pool, size)</literal> — Allocate aligned memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1526 from the specified pool and fill it with zeroes.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1527 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1528
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1529 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1530 <literal>ngx_pnalloc(pool, size)</literal> — Allocate unaligned memory from the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1531 specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1532 Mostly used for allocating strings.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1533 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1534
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1535 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1536 <literal>ngx_pfree(pool, p)</literal> — Free memory that was previously
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1537 allocated in the specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1538 Only allocations that result from requests forwarded to the system allocator
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1539 can be freed.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1540 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1541
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1542 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1543 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1544
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1545 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1546 u_char *p;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1547 ngx_str_t *s;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1548 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1549
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1550 pool = ngx_create_pool(1024, log);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1551 if (pool == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1552
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1553 s = ngx_palloc(pool, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1554 if (s == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1555 ngx_str_set(s, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1556
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1557 p = ngx_pnalloc(pool, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1558 if (p == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1559 ngx_memcpy(p, "foo", 3);
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1560 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1561
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1562 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1563 Chain links (<literal>ngx_chain_t</literal>) are actively used in nginx,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1564 so the nginx pool implementation provides a way to reuse them.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1565 The <literal>chain</literal> field of <literal>ngx_pool_t</literal> keeps a
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1566 list of previously allocated links ready for reuse.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1567 For efficient allocation of a chain link in a pool, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1568 <literal>ngx_alloc_chain_link(pool)</literal> function.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1569 This function looks up a free chain link in the pool list and allocates a new
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1570 chain link if the pool list is empty.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1571 To free a link, call the <literal>ngx_free_chain(pool, cl)</literal> function.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1572 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1573
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1574 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1575 Cleanup handlers can be registered in a pool.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1576 A cleanup handler is a callback with an argument which is called when pool is
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1577 destroyed.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1578 A pool is usually tied to a specific nginx object (like an HTTP request) and is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1579 destroyed when the object reaches the end of its lifetime.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1580 Registering a pool cleanup is a convenient way to release resources, close
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1581 file descriptors or make final adjustments to the shared data associated with
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1582 the main object.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1583 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1584
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1585 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1586 To register a pool cleanup, call
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1587 <literal>ngx_pool_cleanup_add(pool, size)</literal>, which returns a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1588 <literal>ngx_pool_cleanup_t</literal> pointer to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1589 be filled in by the caller.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1590 Use the <literal>size</literal> argument to allocate context for the cleanup
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1591 handler.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1592 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1593
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1594
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1595 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1596 ngx_pool_cleanup_t *cln;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1597
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1598 cln = ngx_pool_cleanup_add(pool, 0);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1599 if (cln == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1600
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1601 cln->handler = ngx_my_cleanup;
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1602 cln->data = "foo";
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1603
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1604 ...
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1605
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1606 static void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1607 ngx_my_cleanup(void *data)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1608 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1609 u_char *msg = data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1610
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1611 ngx_do_smth(msg);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1612 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1613 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1614
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1615 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1616
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1617
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1618 <section name="Shared memory" id="shared_memory">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1619
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1620 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1621 Shared memory is used by nginx to share common data between processes.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1622 The <literal>ngx_shared_memory_add(cf, name, size, tag)</literal> function adds
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1623 a new shared memory entry <literal>ngx_shm_zone_t</literal> to a cycle.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1624 The function receives the <literal>name</literal> and <literal>size</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1625 of the zone.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1626 Each shared zone must have a unique name.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1627 If a shared zone entry with the provided <literal>name</literal> and
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1628 <literal>tag</literal> already exists, the existing zone entry is reused.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1629 The function fails with an error if an existing entry with the same name has a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1630 different tag.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1631 Usually, the address of the module structure is passed as
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1632 <literal>tag</literal>, making it possible to reuse shared zones by name within
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1633 one nginx module.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1634 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1635
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1636 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1637 The shared memory entry structure <literal>ngx_shm_zone_t</literal> has the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1638 following fields:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1639 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1640
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1641 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1642 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1643
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1644 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1645 <literal>init</literal> — Initialization callback, called after the shared zone
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1646 is mapped to actual memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1647 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1648
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1649 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1650 <literal>data</literal> — Data context, used to pass arbitrary data to the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1651 <literal>init</literal> callback
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1652 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1653
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1654 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1655 <literal>noreuse</literal> — Flag that disables reuse of a shared zone from the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1656 old cycle
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1657 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1658
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1659 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1660 <literal>tag</literal> — Shared zone tag
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1661 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1662
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1663 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1664 <literal>shm</literal> — Platform-specific object of type
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1665 <literal>ngx_shm_t</literal>, having at least the following fields:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1666 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1667
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1668 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1669 <literal>addr</literal> — Mapped shared memory address, initially NULL
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1670 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1671
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1672 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1673 <literal>size</literal> — Shared memory size
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1674 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1675
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1676 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1677 <literal>name</literal> — Shared memory name
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1678 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1679
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1680 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1681 <literal>log</literal> — Shared memory log
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1682 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1683
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1684 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1685 <literal>exists</literal> — Flag that indicates shared memory was inherited
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1686 from the master process (Windows-specific)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1687 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1688
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1689 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1690 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1691
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1692 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1693 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1694
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1695 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1696 Shared zone entries are mapped to actual memory in
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1697 <literal>ngx_init_cycle()</literal> after the configuration is parsed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1698 On POSIX systems, the <literal>mmap()</literal> syscall is used to create the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1699 shared anonymous mapping.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1700 On Windows, the <literal>CreateFileMapping()</literal>/
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1701 <literal>MapViewOfFileEx()</literal> pair is used.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1702 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1703
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1704 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1705 For allocating in shared memory, nginx provides the slab pool
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1706 <literal>ngx_slab_pool_t</literal> type.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1707 A slab pool for allocating memory is automatically created in each nginx shared
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1708 zone.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1709 The pool is located in the beginning of the shared zone and can be accessed by
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1710 the expression <literal>(ngx_slab_pool_t *) shm_zone->shm.addr</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1711 To allocate memory in a shared zone, call either
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1712 <literal>ngx_slab_alloc(pool, size)</literal> or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1713 <literal>ngx_slab_calloc(pool, size)</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1714 To free memory, call <literal>ngx_slab_free(pool, p)</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1715 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1716
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1717 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1718 Slab pool divides all shared zone into pages.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1719 Each page is used for allocating objects of the same size.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1720 The specified size must be a power of 2, and greater than the minimum size of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1721 8 bytes.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1722 Nonconforming values are rounded up.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1723 A bitmask for each page tracks which blocks are in use and which are free for
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1724 allocation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1725 For sizes greater than a half page (which is usually 2048 bytes), allocation is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1726 done an entire page at a time
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1727 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1728
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1729 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1730 To protect data in shared memory from concurrent access, use the mutex
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1731 available in the <literal>mutex</literal> field of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1732 <literal>ngx_slab_pool_t</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1733 A mutex is most commonly used by the slab pool while allocating and freeing
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1734 memory, but it can be used to protect any other user data structures allocated
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1735 in the shared zone.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1736 To lock or unlock a mutex, call
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1737 <literal>ngx_shmtx_lock(&shpool->mutex)</literal> or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1738 <literal>ngx_shmtx_unlock(&shpool->mutex)</literal> respectively.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1739 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1740
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1741
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1742 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1743 ngx_str_t name;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1744 ngx_foo_ctx_t *ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1745 ngx_shm_zone_t *shm_zone;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1746
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1747 ngx_str_set(&name, "foo");
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1748
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1749 /* allocate shared zone context */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1750 ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1751 if (ctx == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1752 /* error */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1753 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1754
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1755 /* add an entry for 64k shared zone */
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1756 shm_zone = ngx_shared_memory_add(cf, &name, 65536, &ngx_foo_module);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1757 if (shm_zone == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1758 /* error */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1759 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1760
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1761 /* register init callback and context */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1762 shm_zone->init = ngx_foo_init_zone;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1763 shm_zone->data = ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1764
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1765
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1766 ...
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1767
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1768
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1769 static ngx_int_t
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1770 ngx_foo_init_zone(ngx_shm_zone_t shm_zone, void data)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1771 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1772 ngx_foo_ctx_t *octx = data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1773
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1774 size_t len;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1775 ngx_foo_ctx_t *ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1776 ngx_slab_pool_t *shpool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1777
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1778 value = shm_zone->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1779
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1780 if (octx) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1781 /* reusing a shared zone from old cycle */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1782 ctx->value = octx->value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1783 return NGX_OK;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1784 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1785
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1786 shpool = (ngx_slab_pool_t *) shm_zone->shm.addr;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1787
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1788 if (shm_zone->shm.exists) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1789 /* initialize shared zone context in Windows nginx worker */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1790 ctx->value = shpool->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1791 return NGX_OK;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1792 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1793
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1794 /* initialize shared zone */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1795
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1796 ctx->value = ngx_slab_alloc(shpool, sizeof(ngx_uint_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1797 if (ctx->value == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1798 return NGX_ERROR;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1799 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1800
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1801 shpool->data = ctx->value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1802
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1803 return NGX_OK;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1804 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1805 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1806
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1807 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1808
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1809
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1810 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1811
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1812
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1813 <section name="Logging" id="logging">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1814
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1815 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1816 For logging nginx uses <literal>ngx_log_t</literal> objects.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1817 The nginx logger supports several types of output:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1818
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1819 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1820
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1821 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1822 stderr — Logging to standard error (stderr)
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1823 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1824
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1825 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1826 file — Logging to a file
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1827 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1828
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1829 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1830 syslog — Logging to syslog
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1831 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1832
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1833 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1834 memory — Logging to internal memory storage for development purposes; the memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1835 can be accessed later with a debugger
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1836 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1837
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1838 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1839 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1840
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1841 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1842 A logger instance can be a chain of loggers, linked to each other with
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1843 the <literal>next</literal> field.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1844 In this case, each message is written to all loggers in the chain.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1845 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1846
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1847 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1848 For each logger, a severity level controls which messages are written to the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1849 log (only events assigned that level or higher are logged).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1850 The following severity levels are supported:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1851 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1852
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1853 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1854 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1855
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1856 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1857 <literal>NGX_LOG_EMERG</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1858 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1859
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1860 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1861 <literal>NGX_LOG_ALERT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1862 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1863
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1864 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1865 <literal>NGX_LOG_CRIT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1866 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1867
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1868 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1869 <literal>NGX_LOG_ERR</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1870 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1871
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1872 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1873 <literal>NGX_LOG_WARN</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1874 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1875
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1876 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1877 <literal>NGX_LOG_NOTICE</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1878 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1879
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1880 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1881 <literal>NGX_LOG_INFO</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1882 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1883
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1884 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1885 <literal>NGX_LOG_DEBUG</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1886 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1887
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1888 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1889 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1890
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1891 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1892 For debug logging, the debug mask is checked as well.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1893 The debug masks are:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1894 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1895
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1896 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1897 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1898
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1899 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1900 <literal>NGX_LOG_DEBUG_CORE</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1901 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1902
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1903 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1904 <literal>NGX_LOG_DEBUG_ALLOC</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1905 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1906
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1907 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1908 <literal>NGX_LOG_DEBUG_MUTEX</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1909 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1910
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1911 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1912 <literal>NGX_LOG_DEBUG_EVENT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1913 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1914
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1915 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1916 <literal>NGX_LOG_DEBUG_HTTP</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1917 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1918
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1919 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1920 <literal>NGX_LOG_DEBUG_MAIL</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1921 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1922
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1923 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1924 <literal>NGX_LOG_DEBUG_STREAM</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1925 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1926
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1927 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1928 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1929
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1930 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1931 Normally, loggers are created by existing nginx code from
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1932 <literal>error_log</literal> directives and are available at nearly every stage
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1933 of processing in cycle, configuration, client connection and other objects.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1934 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1935
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1936 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1937 Nginx provides the following logging macros:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1938 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1939
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1940 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1941 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1942
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1943 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1944 <literal>ngx_log_error(level, log, err, fmt, ...)</literal> — Error logging
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1945 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1946
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1947 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1948 <literal>ngx_log_debug0(level, log, err, fmt)</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1949 <literal>ngx_log_debug1(level, log, err, fmt, arg1)</literal> etc — Debug
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1950 logging with up to eight supported formatting arguments
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1951 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1952
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1953 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1954 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1955
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1956 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1957 A log message is formatted in a buffer of size
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1958 <literal>NGX_MAX_ERROR_STR</literal> (currently, 2048 bytes) on stack.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1959 The message is prepended with the severity level, process ID (PID), connection
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1960 ID (stored in <literal>log->connection</literal>), and the system error text.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1961 For non-debug messages <literal>log->handler</literal> is called as well to
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1962 prepend more specific information to the log message.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1963 HTTP module sets <literal>ngx_http_log_error()</literal> function as log
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1964 handler to log client and server addresses, current action (stored in
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1965 <literal>log->action</literal>), client request line, server name etc.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1966 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1967
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1968 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1969 /* specify what is currently done */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1970 log->action = "sending mp4 to client”;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1971
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1972 /* error and debug log */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1973 ngx_log_error(NGX_LOG_INFO, c->log, 0, "client prematurely
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1974 closed connection”);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1975
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1976 ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1977 "mp4 start:%ui, length:%ui”, mp4->start, mp4->length);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1978 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1979
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1980 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1981 The example above results in log entries like these:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1982 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1983
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1984
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1985 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1986 2016/09/16 22:08:52 [info] 17445#0: *1 client prematurely closed connection while
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1987 sending mp4 to client, client: 127.0.0.1, server: , request: "GET /file.mp4 HTTP/1.1”
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1988 2016/09/16 23:28:33 [debug] 22140#0: *1 mp4 start:0, length:10000
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1989 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1990
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1991 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1992
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1993
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1994 <section name="Cycle" id="cycle">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1995
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1996 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1997 A cycle object stores the nginx runtime context created from a specific
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1998 configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1999 Its type is <literal>ngx_cycle_t</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2000 The current cycle is referenced by the <literal>ngx_cycle</literal> global
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2001 variable and inherited by nginx workers as they start.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2002 Each time the nginx configuration is reloaded, a new cycle is created from the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2003 new nginx configuration; the old cycle is usually deleted after the new one is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2004 successfully created.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2005 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2006
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2007 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2008 A cycle is created by the <literal>ngx_init_cycle()</literal> function, which
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2009 takes the previous cycle as its argument.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2010 The function locates the previous cycle's configuration file and inherits as
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2011 many resources as possible from the previous cycle.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2012 A placeholder cycle called "init cycle" is created as nginx start, then is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2013 replaced by an actual cycle built from configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2014 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2015
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2016 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2017 Members of the cycle include:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2018 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2019
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2020 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2021 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2022
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2023 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2024 <literal>pool</literal> — Cycle pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2025 Created for each new cycle.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2026 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2027
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2028 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2029 <literal>log</literal> — Cycle log.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2030 Initially inherited from the old cycle, it is set to point to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2031 <literal>new_log</literal> after the configuration is read.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2032 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2033
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2034 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2035 <literal>new_log</literal> — Cycle log, created by the configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2036 It's affected by the root-scope <literal>error_log</literal> directive.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2037 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2038
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2039 <listitem>
1981 082724c57c38 Fixes in cycle section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1980 diff changeset	2040 <literal>connections</literal>, <literal>connection_n</literal> —
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2041 Array of connections of type <literal>ngx_connection_t</literal>, created by
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2042 the event module while initializing each nginx worker.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2043 The <literal>worker_connections</literal> directive in the nginx configuration
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2044 sets the number of connections <literal>connection_n</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2045 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2046
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2047 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2048 <literal>free_connections</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2049 <literal>free_connection_n</literal> — List and number of currently available
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2050 connections.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2051 If no connections are available, an nginx worker refuses to accept new clients
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2052 or connect to upstream servers.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2053 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2054
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2055 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2056 <literal>files</literal>, <literal>files_n</literal> — Array for mapping file
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2057 descriptors to nginx connections.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2058 This mapping is used by the event modules, having the
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2059 <literal>NGX_USE_FD_EVENT</literal> flag (currently, it's
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2060 <literal>poll</literal> and <literal>devpoll</literal>).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2061 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2062
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2063 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2064 <literal>conf_ctx</literal> — Array of core module configurations.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2065 The configurations are created and filled during reading of nginx configuration
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2066 files.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2067 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2068
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2069 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2070 <literal>modules</literal>, <literal>modules_n</literal> — Array of modules
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2071 of type <literal>ngx_module_t</literal>, both static and dynamic, loaded by
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2072 the current configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2073 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2074
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2075 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2076 <literal>listening</literal> — Array of listening objects of type
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2077 <literal>ngx_listening_t</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2078 Listening objects are normally added by the <literal>listen</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2079 directive of different modules which call the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2080 <literal>ngx_create_listening()</literal> function.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2081 Listen sockets are created based on the listening objects.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2082 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2083
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2084 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2085 <literal>paths</literal> — Array of paths of type <literal>ngx_path_t</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2086 Paths are added by calling the function <literal>ngx_add_path()</literal> from
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2087 modules which are going to operate on certain directories.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2088 These directories are created by nginx after reading configuration, if missing.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2089 Moreover, two handlers can be added for each path:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2090
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2091 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2092
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2093 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2094 path loader — Executes only once in 60 seconds after starting or reloading
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2095 nginx.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2096 Normally, the loader reads the directory and stores data in nginx shared
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2097 memory.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2098 The handler is called from the dedicated nginx process “nginx cache loader”.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2099 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2100
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2101 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2102 path manager — Executes periodically.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2103 Normally, the manager removes old files from the directory and updates nginx
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2104 memory to reflect the changes.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2105 The handler is called from the dedicated “nginx cache manager” process.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2106 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2107
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2108 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2109 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2110
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2111 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2112 <literal>open_files</literal> — List of open file objects of type
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2113 <literal>ngx_open_file_t</literal>, which are created by calling the function
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2114 <literal>ngx_conf_open_file()</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2115 Currently, nginx uses this kind of open files for logging.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2116 After reading the configuration, nginx opens all files in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2117 <literal>open_files</literal> list and stores each file descriptor in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2118 object's <literal>fd</literal> field.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2119 The files are opened in append mode and are created if missing.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2120 The files in the list are reopened by nginx workers upon receiving the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2121 reopen signal (most often <literal>USR1</literal>).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2122 In this case the descriptor in the <literal>fd</literal> field is changed to a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2123 new value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2124 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2125
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2126 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2127 <literal>shared_memory</literal> — List of shared memory zones, each added by
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2128 calling the <literal>ngx_shared_memory_add()</literal> function.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2129 Shared zones are mapped to the same address range in all nginx processes and
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2130 are used to share common data, for example the HTTP cache in-memory tree.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2131 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2132
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2133 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2134 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2135
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2136 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2137
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2138 <section name="Buffer" id="buffer">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2139
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2140 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2141 For input/output operations, nginx provides the buffer type
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2142 <literal>ngx_buf_t</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2143 Normally, it's used to hold data to be written to a destination or read from a
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2144 source.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2145 A buffer can reference data in memory or in a file and it's technically
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2146 possible for a buffer to reference both at the same time.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2147 Memory for the buffer is allocated separately and is not related to the buffer
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2148 structure <literal>ngx_buf_t</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2149 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2150
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2151 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2152 The <literal>ngx_buf_t</literal> structure has the following fields:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2153 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2154
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2155 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2156 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2157
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2158 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2159 <literal>start</literal>, <literal>end</literal> — The boundaries of the memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2160 block allocated for the buffer.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2161 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2162
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2163 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2164 <literal>pos</literal>, <literal>last</literal> — The boundaries of the memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2165 buffer; normally a subrange of <literal>start</literal> ..
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2166 <literal>end</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2167 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2168
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2169 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2170 <literal>file_pos</literal>, <literal>file_last</literal> — The boundaries of a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2171 file buffer, expressed as offsets from the beginning of the file.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2172 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2173
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2174 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2175 <literal>tag</literal> — Unique value used to distinguish buffers; created by
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2176 different nginx modules, usually for the purpose of buffer reuse.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2177 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2178
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2179 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2180 <literal>file</literal> — File object.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2181 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2182
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2183 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2184 <literal>temporary</literal> — Flag indicating that the buffer references
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2185 writable memory.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2186 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2187
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2188 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2189 <literal>memory</literal> — Flag indicating that the buffer references read-only
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2190 memory.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2191 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2192
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2193 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2194 <literal>in_file</literal> — Flag indicating that the buffer references data
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2195 in a file.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2196 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2197
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2198 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2199 <literal>flush</literal> — Flag indicating that all data prior to the buffer
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2200 need to be flushed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2201 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2202
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2203 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2204 <literal>recycled</literal> — Flag indicating that the buffer can be reused and
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2205 needs to be consumed as soon as possible.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2206 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2207
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2208 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2209 <literal>sync</literal> — Flag indicating that the buffer carries no data or
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2210 special signal like <literal>flush</literal> or <literal>last_buf</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2211 By default nginx considers such buffers an error condition, but this flag tells
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2212 nginx to skip the error check.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2213 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2214
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2215 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2216 <literal>last_buf</literal> — Flag indicating that the buffer is the last in
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2217 output.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2218 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2219
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2220 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2221 <literal>last_in_chain</literal> — Flag indicating that there are no more data
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2222 buffers in a request or subrequest.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2223 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2224
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2225 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2226 <literal>shadow</literal> — Reference to another ("shadow") buffer related to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2227 the current buffer, usually in the sense that the buffer uses data from the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2228 shadow.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2229 When the buffer is consumed, the shadow buffer is normally also marked as
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2230 consumed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2231 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2232
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2233 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2234 <literal>last_shadow</literal> — Flag indicating that the buffer is the last
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2235 one that references a particular shadow buffer.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2236 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2237
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2238 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2239 <literal>temp_file</literal> — Flag indicating that the buffer is in a temporary
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2240 file.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2241 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2242
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2243 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2244 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2245
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2246 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2247 For input and output operations buffers are linked in chains.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2248 A chain is a sequence of chain links of type <literal>ngx_chain_t</literal>,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2249 defined as follows:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2250 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2251
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2252
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2253 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2254 typedef struct ngx_chain_s ngx_chain_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2255
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2256 struct ngx_chain_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2257 ngx_buf_t *buf;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2258 ngx_chain_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2259 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2260 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2261
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2262 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2263 Each chain link keeps a reference to its buffer and a reference to the next
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2264 chain link.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2265 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2266
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2267 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2268 An example of using buffers and chains:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2269 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2270
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2271
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2272 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2273 ngx_chain_t *
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2274 ngx_get_my_chain(ngx_pool_t *pool)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2275 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2276 ngx_buf_t *b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2277 ngx_chain_t out, cl, **ll;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2278
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2279 /* first buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2280 cl = ngx_alloc_chain_link(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2281 if (cl == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2282
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2283 b = ngx_calloc_buf(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2284 if (b == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2285
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2286 b->start = (u_char *) "foo";
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2287 b->pos = b->start;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2288 b->end = b->start + 3;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2289 b->last = b->end;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2290 b->memory = 1; /* read-only memory */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2291
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2292 cl->buf = b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2293 out = cl;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2294 ll = &cl->next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2295
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2296 /* second buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2297 cl = ngx_alloc_chain_link(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2298 if (cl == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2299
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2300 b = ngx_create_temp_buf(pool, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2301 if (b == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2302
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2303 b->last = ngx_cpymem(b->last, "foo", 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2304
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2305 cl->buf = b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2306 cl->next = NULL;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2307 *ll = cl;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2308
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2309 return out;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2310 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2311 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2312
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2313 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2314
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2315
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2316 <section name="Networking" id="networking">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2317
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2318
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2319 <!--
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2320 <section name="Network data types" id="network_data_types">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2321
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2322 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2323 TBD: ngx_addr_t, ngx_url_t, ngx_socket_t, ngx_sockaddr_t, parse url, parse
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2324 address...
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2325 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2326
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2327 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2328 -->
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2329
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2330 <section name="Connection" id="connection">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2331
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2332 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2333 The connection type <literal>ngx_connection_t</literal> is a wrapper around a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2334 socket descriptor.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2335 It includes the following fields:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2336 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2337
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2338 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2339 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2340
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2341 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2342 <literal>fd</literal> — Socket descriptor
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2343 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2344
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2345 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2346 <literal>data</literal> — Arbitrary connection context.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2347 Normally, it is a pointer to a higher-level object built on top of the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2348 connection, such as an HTTP request or a Stream session.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2349 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2350
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2351 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2352 <literal>read</literal>, <literal>write</literal> — Read and write events for
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2353 the connection.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2354 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2355
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2356 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2357 <literal>recv</literal>, <literal>send</literal>,
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2358 <literal>recv_chain</literal>, <literal>send_chain</literal> — I/O operations
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2359 for the connection.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2360 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2361
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2362 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2363 <literal>pool</literal> — Connection pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2364 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2365
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2366 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2367 <literal>log</literal> — Connection log.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2368 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2369
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2370 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2371 <literal>sockaddr</literal>, <literal>socklen</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2372 <literal>addr_text</literal> — Remote socket address in binary and text forms.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2373 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2374
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2375 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2376 <literal>local_sockaddr</literal>, <literal>local_socklen</literal> — Local
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2377 socket address in binary form.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2378 Initially, these fields are empty.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2379 Use the <literal>ngx_connection_local_sockaddr()</literal> function to get the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2380 local socket address.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2381 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2382
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2383 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2384 <literal>proxy_protocol_addr</literal>, <literal>proxy_protocol_port</literal>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2385 - PROXY protocol client address and port, if the PROXY protocol is enabled for
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2386 the connection.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2387 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2388
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2389 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2390 <literal>ssl</literal> — SSL context for the connection.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2391 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2392
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2393 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2394 <literal>reusable</literal> — Flag indicating the connection is in a state that
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2395 makes it eligible for reuse.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2396 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2397
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2398 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2399 <literal>close</literal> — Flag indicating that the connection is being reused
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2400 and needs to be closed.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2401 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2402
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2403 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2404 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2405
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2406 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2407 An nginx connection can transparently encapsulate the SSL layer.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2408 In this case the connection's <literal>ssl</literal> field holds a pointer to an
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2409 <literal>ngx_ssl_connection_t</literal> structure, keeping all SSL-related data
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2410 for the connection, including <literal>SSL_CTX</literal> and
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2411 <literal>SSL</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2412 The <literal>recv</literal>, <literal>send</literal>,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2413 <literal>recv_chain</literal>, and <literal>send_chain</literal> handlers are
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2414 set to SSL-enabled functions as well.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2415 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2416
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2417 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2418 The <literal>worker_connections</literal> directive in the nginx configuration
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2419 limits the number of connections per nginx worker.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2420 All connection structures are precreated when a worker starts and stored in
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2421 the <literal>connections</literal> field of the cycle object.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2422 To retrieve a connection structure, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2423 <literal>ngx_get_connection(s, log)</literal> function.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2424 It takes as its <literal>s</literal> argument a socket descriptor, which needs
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2425 to be wrapped in a connection structure.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2426 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2427
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2428 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2429 Because the number of connections per worker is limited, nginx provides a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2430 way to grab connections that are currently in use.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2431 To enable or disable reuse of a connection, call the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2432 <literal>ngx_reusable_connection(c, reusable)</literal> function.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2433 Calling <literal>ngx_reusable_connection(c, 1)</literal> sets the
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2434 <literal>reuse</literal> flag in the connection structure and inserts the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2435 connection into the <literal>reusable_connections_queue</literal> of the cycle.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2436 Whenever <literal>ngx_get_connection()</literal> finds out there are no
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2437 available connections in the cycle's <literal>free_connections</literal> list,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2438 it calls <literal>ngx_drain_connections()</literal> to release a
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2439 specific number of reusable connections.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2440 For each such connection, the <literal>close</literal> flag is set and its read
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2441 handler is called which is supposed to free the connection by calling
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2442 <literal>ngx_close_connection(c)</literal> and make it available for reuse.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2443 To exit the state when a connection can be reused
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2444 <literal>ngx_reusable_connection(c, 0)</literal> is called.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2445 HTTP client connections are an example of reusable connections in nginx; they
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2446 are marked as reusable until the first request byte is received from the client.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2447 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2448
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2449 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2450
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2451
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2452 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2453
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2454
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2455 <section name="Events" id="events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2456
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2457
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2458 <section name="Event" id="event">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2459
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2460 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2461 Event object <literal>ngx_event_t</literal> in nginx provides a mechanism
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2462 for notification that a specific event has occurred.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2463 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2464
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2465 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2466 Fields in <literal>ngx_event_t</literal> include:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2467 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2468
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2469 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2470 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2471
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2472 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2473 <literal>data</literal> — Arbitrary event context used in event handlers,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2474 usually as pointer to a connection related to the event.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2475 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2476
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2477 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2478 <literal>handler</literal> — Callback function to be invoked when the event
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2479 happens.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2480 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2481
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2482 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2483 <literal>write</literal> — Flag indicating a write event.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2484 Absence of the flag indicates a read event.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2485 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2486
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2487 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2488 <literal>active</literal> — Flag indicating that the event is registered for
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2489 receiving I/O notifications, normally from notification mechanisms like
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2490 <literal>epoll</literal>, <literal>kqueue</literal>, <literal>poll</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2491 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2492
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2493 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2494 <literal>ready</literal> — Flag indicating that the event has received an
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2495 I/O notification.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2496 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2497
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2498 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2499 <literal>delayed</literal> — Flag indicating that I/O is delayed due to rate
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2500 limiting.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2501 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2502
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2503 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2504 <literal>timer</literal> — Red-black tree node for inserting the event into
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2505 the timer tree.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2506 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2507
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2508 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2509 <literal>timer_set</literal> — Flag indicating that the event timer is set and
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2510 not yet expired.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2511 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2512
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2513 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2514 <literal>timedout</literal> — Flag indicating that the event timer has expired.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2515 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2516
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2517 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2518 <literal>eof</literal> — Flag indicating that EOF occurred while reading data.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2519 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2520
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2521 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2522 <literal>pending_eof</literal> — Flag indicating that EOF is pending on the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2523 socket, even though there may be some data available before it.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2524 The flag is delivered via the <literal>EPOLLRDHUP</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2525 <literal>epoll</literal> event or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2526 <literal>EV_EOF</literal> <literal>kqueue</literal> flag.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2527 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2528
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2529 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2530 <literal>error</literal> — Flag indicating that an error occurred during
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2531 reading (for a read event) or writing (for a write event).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2532 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2533
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2534 <listitem>
1995 80f53da7280c Updated cancelable event description in the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1994 diff changeset	2535 <literal>cancelable</literal> — Timer event flag indicating that the event
80f53da7280c Updated cancelable event description in the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1994 diff changeset	2536 should be ignored while shutting down the worker.
80f53da7280c Updated cancelable event description in the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1994 diff changeset	2537 Graceful worker shutdown is delayed until there are no non-cancelable timer
80f53da7280c Updated cancelable event description in the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1994 diff changeset	2538 events scheduled.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2539 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2540
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2541 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2542 <literal>posted</literal> — Flag indicating that the event is posted to a queue.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2543 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2544
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2545 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2546 <literal>queue</literal> — Queue node for posting the event to a queue.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2547 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2548
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2549 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2550 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2551
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2552 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2553
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2554
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2555 <section name="I/O events" id="i_o_events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2556
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2557 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2558 Each connection obtained by calling the <literal>ngx_get_connection()</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2559 function has two attached events, <literal>c->read</literal> and
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2560 <literal>c->write</literal>, which are used for receiving notification that the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2561 socket is ready for reading or writing.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2562 All such events operate in Edge-Triggered mode, meaning that they only trigger
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2563 notifications when the state of the socket changes.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2564 For example, doing a partial read on a socket does not make nginx deliver a
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2565 repeated read notification until more data arrives on the socket.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2566 Even when the underlying I/O notification mechanism is essentially
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2567 Level-Triggered (<literal>poll</literal>, <literal>select</literal> etc), nginx
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2568 converts the notifications to Edge-Triggered.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2569 To make nginx event notifications consistent across all notifications systems
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2570 on different platforms, the functions
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2571 <literal>ngx_handle_read_event(rev, flags)</literal> and
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2572 <literal>ngx_handle_write_event(wev, lowat)</literal> must be called after
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2573 handling an I/O socket notification or calling any I/O functions on that socket.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2574 Normally, the functions are called once at the end of each read or write
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2575 event handler.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2576 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2577
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2578 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2579
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2580
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2581 <section name="Timer events" id="timer_events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2582
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2583 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2584 An event can be set to send a notification when a timeout expires.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2585 The function <literal>ngx_add_timer(ev, timer)</literal> sets a timeout for an
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2586 event, <literal>ngx_del_timer(ev)</literal> deletes a previously set timeout.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2587 The global timeout red-black tree <literal>ngx_event_timer_rbtree</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2588 stores all timeouts currently set.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2589 The key in the tree is of type <literal>ngx_msec_t</literal> and is the time
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2590 when the event expires, expressed in milliseconds since the midnight on of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2591 January 1, 1970 modulus <literal>ngx_msec_t</literal> max value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2592 The tree structure enables fast insertion and deletion operations, as well as
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2593 access to the nearest timeouts, which nginx uses to find out how long to wait
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2594 for I/O events and for expiring timeout events.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2595 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2596
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2597 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2598
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2599
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2600 <section name="Posted events" id="posted_events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2601
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2602 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2603 An event can be posted which means that its handler will be called at some
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2604 point later within the current event loop iteration.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2605 Posting events is a good practice for simplifying code and escaping stack
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2606 overflows.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2607 Posted events are held in a post queue.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2608 The <literal>ngx_post_event(ev, q)</literal> mscro posts the event
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2609 <literal>ev</literal> to the post queue <literal>q</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2610 The <literal>ngx_delete_posted_event(ev)</literal> macro deletes the event
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2611 <literal>ev</literal> from the queue it's currently posted in.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2612 Normally, events are posted to the <literal>ngx_posted_events</literal> queue,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2613 which is processed late in the event loop — after all I/O and timer
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2614 events are already handled.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2615 The function <literal>ngx_event_process_posted()</literal> is called to process
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2616 an event queue.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2617 It calls event handlers until the queue is not empty.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2618 This means that a posted event handler can post more events to be processed
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2619 within the current event loop iteration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2620 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2621
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2622 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2623 An example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2624 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2625
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2626
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2627 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2628 void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2629 ngx_my_connection_read(ngx_connection_t *c)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2630 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2631 ngx_event_t *rev;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2632
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2633 rev = c->read;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2634
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2635 ngx_add_timer(rev, 1000);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2636
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2637 rev->handler = ngx_my_read_handler;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2638
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2639 ngx_my_read(rev);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2640 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2641
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2642
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2643 void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2644 ngx_my_read_handler(ngx_event_t *rev)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2645 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2646 ssize_t n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2647 ngx_connection_t *c;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2648 u_char buf[256];
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2649
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2650 if (rev->timedout) { /* timeout expired */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2651
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2652 c = rev->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2653
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2654 while (rev->ready) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2655 n = c->recv(c, buf, sizeof(buf));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2656
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2657 if (n == NGX_AGAIN) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2658 break;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2659 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2660
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2661 if (n == NGX_ERROR) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2662
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2663 /* process buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2664 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2665
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2666 if (ngx_handle_read_event(rev, 0) != NGX_OK) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2667 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2668 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2669
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2670 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2671
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2672
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2673 <section name="Event loop" id="event_loop">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2674
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2675 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2676 Except for the nginx master process, all nginx processes do I/O and so have an
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2677 event loop.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2678 (The nginx master process instead spends most of its time in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2679 <literal>sigsuspend()</literal> call waiting for signals to arrive.)
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2680 The nginx event loop is implemented in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2681 <literal>ngx_process_events_and_timers()</literal> function, which is called
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2682 repeatedly until the process exits.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2683 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2684
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2685 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2686 The event loop has the following stages:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2687
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2688 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2689
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2690 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2691 Find the timeout that is closest to expiring, by calling
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2692 <literal>ngx_event_find_timer()</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2693 This function finds the leftmost node in the timer tree and returns the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2694 number of milliseconds until the node expires.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2695 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2696
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2697 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2698 Process I/O events by calling a handler, specific to the event notification
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2699 mechanism, chosen by nginx configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2700 This handler waits for at least one I/O event to happen, but only until the next
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2701 timeout expires.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2702 When a read or write event occurs, the <literal>ready</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2703 flag is set and the event's handler is called.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2704 For Linux, the <literal>ngx_epoll_process_events()</literal> handler
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2705 is normally used, which calls <literal>epoll_wait()</literal> to wait for I/O
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2706 events.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2707 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2708
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2709 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2710 Expire timers by calling <literal>ngx_event_expire_timers()</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2711 The timer tree is iterated from the leftmost element to the right until an
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2712 unexpired timeout is found.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2713 For each expired node the <literal>timedout</literal> event flag is set,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2714 the <literal>timer_set</literal> flag is reset, and the event handler is called
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2715 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2716
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2717 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2718 Process posted events by calling <literal>ngx_event_process_posted()</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2719 The function repeatedly removes the first element from the posted events
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2720 queue and calls the element's handler, until the queue is empty.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2721 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2722
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2723 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2724 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2725
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2726 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2727 All nginx processes handle signals as well.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2728 Signal handlers only set global variables which are checked after the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2729 <literal>ngx_process_events_and_timers()</literal> call.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2730 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2731
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2732 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2733
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2734
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2735 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2736
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2737
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2738 <section name="Processes" id="processes">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2739
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2740 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2741 There are several types of processes in nginx.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2742 The type of a process is kept in the <literal>ngx_process</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2743 global variable, and is one of the following:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2744 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2745
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2746 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2747
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2748 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2749
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2750 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2751 <literal>NGX_PROCESS_MASTER</literal> — The master process, which reads the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2752 NGINX configuration, creates cycles, and starts and controls child processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2753 It does not perform any I/O and responds only to signals.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2754 Its cycle function is <literal>ngx_master_process_cycle()</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2755 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2756
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2757
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2758 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2759
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2760 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2761
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2762 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2763 <literal>NGX_PROCESS_WORKER</literal> — The worker process, which handles client
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2764 connections.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2765 It is started by the master process and responds to its signals and channel
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2766 commands as well.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2767 Its cycle function is <literal>ngx_worker_process_cycle()</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2768 There can be multiple worker processes, as configured by the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2769 <literal>worker_processes</literal> directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2770 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2771
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2772 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2773
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2774 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2775
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2776 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2777 <literal>NGX_PROCESS_SINGLE</literal> — The single process, which exists only in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2778 <literal>master_process off</literal> mode, and is the only process running in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2779 that mode.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2780 It creates cycles (like the master process does) and handles client connections
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2781 (like the worker process does).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2782 Its cycle function is <literal>ngx_single_process_cycle()</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2783 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2784
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2785 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2786
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2787 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2788
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2789 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2790 <literal>NGX_PROCESS_HELPER</literal> — The helper process, of which currently
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2791 there are two types: cache manager and cache loader.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2792 The cycle function for both is
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2793 <literal>ngx_cache_manager_process_cycle()</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2794 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2795
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2796 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2797
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2798 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2799
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2800 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2801 The nginx processes handle the following signals:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2802 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2803
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2804 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2805
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2806 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2807
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2808 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2809 <literal>NGX_SHUTDOWN_SIGNAL</literal> (<literal>SIGQUIT</literal> on most
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2810 systems) — Gracefully shutdown.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2811 Upon receiving this signal, the master process sends a shutdown signal to all
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2812 child processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2813 When no child processes are left, the master destroys the cycle pool and exits.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2814 When a worker process receives this signal, it closes all listening sockets and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2815 waits until there are no non-cancelable events scheduled, then destroys the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2816 cycle pool and exits.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2817 When the cache manager or the cache loader process receives this signal, it
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2818 exits immediately.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2819 The <literal>ngx_quit</literal> variable is set to <literal>1</literal> when a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2820 process receives this signal, and is immediately reset after being processed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2821 The <literal>ngx_exiting</literal> variable is set to <literal>1</literal> while
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2822 a worker process is in the shutdown state.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2823 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2824
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2825 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2826
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2827 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2828
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2829 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2830 <literal>NGX_TERMINATE_SIGNAL</literal> (<literal>SIGTERM</literal> on most
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2831 systems) — Terminate.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2832 Upon receiving this signal, the master process sends a terminate signal to all
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2833 child processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2834 If a child process does not exit within 1 second, the master process sends the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2835 <literal>SIGKILL</literal> signal to kill it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2836 When no child processes are left, the master process destroys the cycle pool and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2837 exits.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2838 When a worker process, the cache manager process or the cache loader process
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2839 receives this signal, it destroys the cycle pool and exits.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2840 The variable <literal>ngx_terminate</literal> is set to <literal>1</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2841 when this signal is received.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2842 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2843
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2844 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2845
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2846 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2847
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2848 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2849 <literal>NGX_NOACCEPT_SIGNAL</literal> (<literal>SIGWINCH</literal> on most
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2850 systems) - Shut down all worker and helper processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2851 Upon receiving this signal, the master process shuts down its child processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2852 If a previously started new nginx binary exits, the child processes of the old
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2853 master are started again.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2854 When a worker process receives this signal, it shuts down in debug mode
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2855 set by the <literal>debug_points</literal> directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2856 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2857
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2858
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2859 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2860
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2861 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2862
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2863 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2864 <literal>NGX_RECONFIGURE_SIGNAL</literal> (<literal>SIGHUP</literal> on most
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2865 systems) - Reconfigure.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2866 Upon receiving this signal, the master process re-reads the configuration and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2867 creates a new cycle based on it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2868 If the new cycle is created successfully, the old cycle is deleted and new
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2869 child processes are started.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2870 Meanwhile, the old child processes receive the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2871 <literal>NGX_SHUTDOWN_SIGNAL</literal> signal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2872 In single-process mode, nginx creates a new cycle, but keeps the old one until
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2873 there are no longer clients with active connections tied to it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2874 The worker and helper processes ignore this signal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2875 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2876
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2877 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2878
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2879 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2880
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2881 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2882 <literal>NGX_REOPEN_SIGNAL</literal> (<literal>SIGUSR1</literal> on most
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2883 systems) — Reopen files.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2884 The master process sends this signal to workers, which reopen all
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2885 <literal>open_files</literal> related to the cycle.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2886 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2887
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2888 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2889
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2890 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2891
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2892 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2893 <literal>NGX_CHANGEBIN_SIGNAL</literal> (<literal>SIGUSR2</literal> on most
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2894 systems) — Change the nginx binary.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2895 The master process starts a new nginx binary and passes in a list of all listen
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2896 sockets.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2897 The text-format list, passed in the <literal>“NGINX”</literal> environment
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2898 variable, consists of descriptor numbers separated with semicolons.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2899 The new nginx binary reads the <literal>“NGINX”</literal> variable and adds the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2900 sockets to its init cycle.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2901 Other processes ignore this signal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2902 </para>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2903
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2904 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2905
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2906 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2907
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2908 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2909 While all nginx worker processes are able to receive and properly handle POSIX
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2910 signals, the master process does not use the standard <literal>kill()</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2911 syscall to pass signals to workers and helpers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2912 Instead, nginx uses inter-process socket pairs which allow sending messages
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2913 between all nginx processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2914 Currently, however, messages are only sent from the master to its children.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2915 The messages carry the standard signals.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2916 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2917
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2918 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2919
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2920 <section name="Threads" id="threads">
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2921
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2922 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2923 It is possible to offload into a separate thread tasks that would otherwise
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2924 block the nginx worker process.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2925 For example, nginx can be configured to use threads to perform
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2926 <link doc="../http/ngx_http_core_module.xml" id="aio">file I/O</link>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2927 Another use case is a library that doesn't have asynchronous interface
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2928 and thus cannot be normally used with nginx.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2929 Keep in mind that the threads interface is a helper for the existing
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2930 asynchronous approach to processing client connections, and by no means
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2931 intended as a replacement.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2932 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2933
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2934 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2935 To deal with synchronization, the following wrappers over
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2936 <literal>pthreads</literal> primitives are available:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2937
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2938 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2939
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2940 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2941 <literal>typedef pthread_mutex_t ngx_thread_mutex_t;</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2942
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2943 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2944
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2945 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2946 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2947 ngx_thread_mutex_create(ngx_thread_mutex_t mtx, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2948 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2949
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2950 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2951 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2952 ngx_thread_mutex_destroy(ngx_thread_mutex_t mtx, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2953 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2954
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2955 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2956 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2957 ngx_thread_mutex_lock(ngx_thread_mutex_t mtx, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2958 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2959
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2960 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2961 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2962 ngx_thread_mutex_unlock(ngx_thread_mutex_t mtx, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2963 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2964
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2965 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2966
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2967 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2968
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2969 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2970 <literal>typedef pthread_cond_t ngx_thread_cond_t;</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2971
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2972 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2973
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2974 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2975 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2976 ngx_thread_cond_create(ngx_thread_cond_t cond, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2977 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2978
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2979 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2980 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2981 ngx_thread_cond_destroy(ngx_thread_cond_t cond, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2982 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2983
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2984 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2985 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2986 ngx_thread_cond_signal(ngx_thread_cond_t cond, ngx_log_t log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2987 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2988
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2989 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2990 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2991 ngx_thread_cond_wait(ngx_thread_cond_t cond, ngx_thread_mutex_t mtx,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2992 ngx_log_t *log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2993 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2994
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2995 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2996
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2997 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2998
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2999 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3000
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3001 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3002
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3003 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3004 Instead of creating a new thread for each task, nginx implements
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3005 a <link doc="../ngx_core_module.xml" id="thread_pool"/> strategy.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3006 Multiple thread pools may be configured for different purposes
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3007 (for example, performing I/O on different sets of disks).
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3008 Each thread pool is created at startup and contains a limited number of threads
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3009 that process a queue of tasks.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3010 When a task is completed, a predefined completion handler is called.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3011 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3012
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3013 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3014 The <literal>src/core/ngx_thread_pool.h</literal> header file contains
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3015 relevant definitions:
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3016 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3017 struct ngx_thread_task_s {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3018 ngx_thread_task_t *next;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3019 ngx_uint_t id;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3020 void *ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3021 void (handler)(void data, ngx_log_t *log);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3022 ngx_event_t event;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3023 };
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3024
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3025 typedef struct ngx_thread_pool_s ngx_thread_pool_t;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3026
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3027 ngx_thread_pool_t ngx_thread_pool_add(ngx_conf_t cf, ngx_str_t *name);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3028 ngx_thread_pool_t ngx_thread_pool_get(ngx_cycle_t cycle, ngx_str_t *name);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3029
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3030 ngx_thread_task_t ngx_thread_task_alloc(ngx_pool_t pool, size_t size);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3031 ngx_int_t ngx_thread_task_post(ngx_thread_pool_t tp, ngx_thread_task_t task);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3032
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3033 </programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3034 At configuration time, a module willing to use threads has to obtain a
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3035 reference to a thread pool by calling
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3036 <literal>ngx_thread_pool_add(cf, name)</literal>, which either creates a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3037 new thread pool with the given <literal>name</literal> or returns a reference
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3038 to the pool with that name if it already exists.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3039 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3040
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3041 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3042 To add a <literal>task</literal> into a queue of a specified thread pool
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3043 <literal>tp</literal> at runtime, use the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3044 <literal>ngx_thread_task_post(tp, task)</literal> function.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3045
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3046 To execute a function in a thread, pass parameters and setup a completion
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3047 handler using the <literal>ngx_thread_task_t</literal> structure:
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3048 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3049 typedef struct {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3050 int foo;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3051 } my_thread_ctx_t;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3052
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3053
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3054 static void
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3055 my_thread_func(void data, ngx_log_t log)
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3056 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3057 my_thread_ctx_t *ctx = data;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3058
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3059 /* this function is executed in a separate thread */
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3060 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3061
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3062
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3063 static void
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3064 my_thread_completion(ngx_event_t *ev)
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3065 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3066 my_thread_ctx_t *ctx = ev->data;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3067
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3068 /* executed in nginx event loop */
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3069 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3070
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3071
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3072 ngx_int_t
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3073 my_task_offload(my_conf_t *conf)
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3074 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3075 my_thread_ctx_t *ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3076 ngx_thread_task_t *task;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3077
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3078 task = ngx_thread_task_alloc(conf->pool, sizeof(my_thread_ctx_t));
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3079 if (task == NULL) {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3080 return NGX_ERROR;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3081 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3082
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3083 ctx = task->ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3084
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3085 ctx->foo = 42;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3086
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3087 task->handler = my_thread_func;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3088 task->event.handler = my_thread_completion;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3089 task->event.data = ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3090
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3091 if (ngx_thread_task_post(conf->thread_pool, task) != NGX_OK) {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3092 return NGX_ERROR;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3093 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3094
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3095 return NGX_OK;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3096 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3097 </programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3098
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3099 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3100
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3101 </section>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3102
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3103
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3104 <section name="Modules" id="Modules">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3105
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3106 <section name="Adding new modules" id="adding_new_modules">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3107 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3108 Each standalone nginx module resides in a separate directory that contains
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3109 at least two files:
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3110 <literal>config</literal> and a file with the module source code.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3111 The <literal>config</literal> file contains all information needed for nginx to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3112 integrate the module, for example:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3113 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3114 ngx_module_type=CORE
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3115 ngx_module_name=ngx_foo_module
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3116 ngx_module_srcs="$ngx_addon_dir/ngx_foo_module.c"
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3117
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3118 . auto/module
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3119
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3120 ngx_addon_name=$ngx_module_name
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3121 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3122 The <literal>config</literal> file is a POSIX shell script that can set
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3123 and access the following variables:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3124 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3125
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3126 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3127 <literal>ngx_module_type</literal> — Type of module to build.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3128 Possible values are <literal>CORE</literal>, <literal>HTTP</literal>,
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3129 <literal>HTTP_FILTER</literal>, <literal>HTTP_INIT_FILTER</literal>,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3130 <literal>HTTP_AUX_FILTER</literal>, <literal>MAIL</literal>,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3131 <literal>STREAM</literal>, or <literal>MISC</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3132 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3133
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3134 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3135 <literal>ngx_module_name</literal> — Module names.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3136 To build multiple modules from a set of source files, specify a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3137 whitespace-separated list of names.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3138 The first name indicates the name of the output binary for the dynamic module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3139 The names in the list must match the names used in the source code.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3140 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3141
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3142 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3143 <literal>ngx_addon_name</literal> — Name of the module as it appears in output
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3144 on the console from the configure script.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3145 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3146
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3147 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3148 <literal>ngx_module_srcs</literal> — Whitespace-separated list of source
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3149 files used to compile the module.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3150 The <literal>$ngx_addon_dir</literal> variable can be used to represent the path
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3151 to the module directory.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3152 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3153
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3154 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3155 <literal>ngx_module_incs</literal> — Include paths required to build the module
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3156 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3157
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3158 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3159 <literal>ngx_module_deps</literal> — Whitespace-separated list of the module's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3160 dependencies.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3161 Usually, it is the list of header files.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3162 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3163
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3164 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3165 <literal>ngx_module_libs</literal> — Whitespace-separated list of libraries to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3166 link with the module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3167 For example, use <literal>ngx_module_libs=-lpthread</literal> to link
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3168 <literal>libpthread</literal> library.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3169 The following macros can be used to link against the same libraries as
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3170 nginx:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3171 <literal>LIBXSLT</literal>, <literal>LIBGD</literal>, <literal>GEOIP</literal>,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3172 <literal>PCRE</literal>, <literal>OPENSSL</literal>, <literal>MD5</literal>,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3173 <literal>SHA1</literal>, <literal>ZLIB</literal>, and <literal>PERL</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3174 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3175
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3176 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3177 <literal>ngx_module_link</literal> — Variable set by the build system to
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3178 <literal>DYNAMIC</literal> for a dynamic module or <literal>ADDON</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3179 for a static module and used to determine different actions to perform
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3180 depending on linking type.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3181 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3182
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3183 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3184 <literal>ngx_module_order</literal> — Load order for the module;
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3185 useful for the <literal>HTTP_FILTER</literal> and
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3186 <literal>HTTP_AUX_FILTER</literal> module types.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3187 The format for this option is a whitespace-separated list of modules.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3188 All modules in the list following the current module's name end up after it in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3189 the global list of modules, which sets up the order for modules initialization.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3190 For filter modules later initialization means earlier execution.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3191
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3192 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3193 The following modules are typically used as references.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3194 The <literal>ngx_http_copy_filter_module</literal> reads the data for other
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3195 filter modules and is placed near the bottom of the list so that it is one of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3196 the first to be executed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3197 The <literal>ngx_http_write_filter_module</literal> writes the data to the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3198 client socket and is placed near the top of the list, and is the last to be
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3199 executed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3200 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3201
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3202 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3203 By default, filter modules are placed before the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3204 <literal>ngx_http_copy_filter</literal> in the module list so that the filter
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3205 handler is executed after the copy filter handler.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3206 For other module types the default is the empty string.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3207 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3208
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3209 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3210
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3211 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3212
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3213 To compile a module into nginx statically, use the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3214 <literal>--add-module=/path/to/module</literal> argument to the configure
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3215 script.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3216 To compile a module for later dynamic loading into nginx, use the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3217 <literal>--add-dynamic-module=/path/to/module</literal> argument.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3218 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3219
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3220 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3221
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3222
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3223 <section name="Core Modules" id="core_modules">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3224
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3225 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3226 Modules are the building blocks of nginx, and most of its functionality is
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3227 implemented as modules.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3228 The module source file must contain a global variable of type
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3229 <literal>ngx_module_t</literal>, which is defined as follows:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3230 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3231 struct ngx_module_s {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3232
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3233 /* private part is omitted */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3234
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3235 void *ctx;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3236 ngx_command_t *commands;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3237 ngx_uint_t type;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3238
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3239 ngx_int_t (init_master)(ngx_log_t log);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3240
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3241 ngx_int_t (init_module)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3242
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3243 ngx_int_t (init_process)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3244 ngx_int_t (init_thread)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3245 void (exit_thread)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3246 void (exit_process)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3247
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3248 void (exit_master)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3249
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3250 /* stubs for future extensions are omitted */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3251 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3252 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3253 The omitted private part includes the module version and a signature and is
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3254 filled using the predefined macro <literal>NGX_MODULE_V1</literal>.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3255 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3256
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3257 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3258 Each module keeps its private data in the <literal>ctx</literal> field,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3259 recognizes the configuration directives, specified in the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3260 <literal>commands</literal> array, and can be invoked at certain stages of
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3261 nginx lifecycle.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3262 The module lifecycle consists of the following events:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3263
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3264 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3265
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3266 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3267 Configuration directive handlers are called as they appear
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3268 in configuration files in the context of the master process.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3269 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3270
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3271 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3272 After the configuration is parsed successfully, <literal>init_module</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3273 handler is called in the context of the master process.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3274 The <literal>init_module</literal> handler is called in the master process each
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3275 time a configuration is loaded.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3276 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3277
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3278 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3279 The master process creates one or more worker processes and the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3280 <literal>init_process</literal> handler is called in each of them.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3281 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3282
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3283 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3284 When a worker process receives the shutdown or terminate command from the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3285 master, it invokes the <literal>exit_process</literal> handler.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3286 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3287
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3288 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3289 The master process calls the <literal>exit_master</literal> handler before
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3290 exiting.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3291 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3292
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3293 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3294
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3295 Because threads are used in nginx only as a supplementary I/O facility with its
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3296 own API, <literal>init_thread</literal> and <literal>exit_thread</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3297 handlers are not currently called.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3298 There is also no <literal>init_master</literal> handler, because it would be
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3299 unnecessary overhead.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3300 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3301
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3302 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3303 The module <literal>type</literal> defines exactly what is stored in the
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3304 <literal>ctx</literal> field.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3305 Its value is one of the following types:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3306 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3307 <listitem><literal>NGX_CORE_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3308 <listitem><literal>NGX_EVENT_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3309 <listitem><literal>NGX_HTTP_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3310 <listitem><literal>NGX_MAIL_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3311 <listitem><literal>NGX_STREAM_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3312 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3313 The <literal>NGX_CORE_MODULE</literal> is the most basic and thus the most
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3314 generic and most low-level type of module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3315 The other module types are implemented on top of it and provide a more
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3316 convenient way to deal with corresponding domains, like handling events or HTTP
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3317 requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3318 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3319
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3320 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3321 The set of core modules includes <literal>ngx_core_module</literal>,
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3322 <literal>ngx_errlog_module</literal>, <literal>ngx_regex_module</literal>,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3323 <literal>ngx_thread_pool_module</literal> and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3324 <literal>ngx_openssl_module</literal> modules.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3325 The HTTP module, the stream module, the mail module and event modules are core
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3326 modules too.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3327 The context of a core module is defined as:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3328 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3329 typedef struct {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3330 ngx_str_t name;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3331 void (create_conf)(ngx_cycle_t *cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3332 char (init_conf)(ngx_cycle_t cycle, void conf);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3333 } ngx_core_module_t;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3334 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3335 where the <literal>name</literal> is a module name string,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3336 <literal>create_conf</literal> and <literal>init_conf</literal>
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3337 are pointers to functions that create and initialize module configuration
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3338 respectively.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3339 For core modules, nginx calls <literal>create_conf</literal> before parsing
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3340 a new configuration and <literal>init_conf</literal> after all configuration
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3341 is parsed successfully.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3342 The typical <literal>create_conf</literal> function allocates memory for the
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3343 configuration and sets default values.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3344 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3345
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3346 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3347 For example, a simplistic module called <literal>ngx_foo_module</literal> might
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3348 look like this:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3349 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3350 /*
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3351 * Copyright (C) Author.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3352 */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3353
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3354
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3355 #include <ngx_config.h>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3356 #include <ngx_core.h>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3357
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3358
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3359 typedef struct {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3360 ngx_flag_t enable;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3361 } ngx_foo_conf_t;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3362
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3363
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3364 static void ngx_foo_create_conf(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3365 static char ngx_foo_init_conf(ngx_cycle_t cycle, void *conf);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3366
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3367 static char ngx_foo_enable(ngx_conf_t cf, void post, void data);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3368 static ngx_conf_post_t ngx_foo_enable_post = { ngx_foo_enable };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3369
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3370
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3371 static ngx_command_t ngx_foo_commands[] = {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3372
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3373 { ngx_string("foo_enabled"),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3374 NGX_MAIN_CONF\|NGX_DIRECT_CONF\|NGX_CONF_FLAG,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3375 ngx_conf_set_flag_slot,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3376 0,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3377 offsetof(ngx_foo_conf_t, enable),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3378 &ngx_foo_enable_post },
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3379
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3380 ngx_null_command
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3381 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3382
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3383
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3384 static ngx_core_module_t ngx_foo_module_ctx = {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3385 ngx_string("foo"),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3386 ngx_foo_create_conf,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3387 ngx_foo_init_conf
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3388 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3389
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3390
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3391 ngx_module_t ngx_foo_module = {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3392 NGX_MODULE_V1,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3393 &ngx_foo_module_ctx, /* module context */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3394 ngx_foo_commands, /* module directives */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3395 NGX_CORE_MODULE, /* module type */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3396 NULL, /* init master */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3397 NULL, /* init module */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3398 NULL, /* init process */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3399 NULL, /* init thread */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3400 NULL, /* exit thread */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3401 NULL, /* exit process */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3402 NULL, /* exit master */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3403 NGX_MODULE_V1_PADDING
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3404 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3405
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3406
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3407 static void *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3408 ngx_foo_create_conf(ngx_cycle_t *cycle)
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3409 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3410 ngx_foo_conf_t *fcf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3411
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3412 fcf = ngx_pcalloc(cycle->pool, sizeof(ngx_foo_conf_t));
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3413 if (fcf == NULL) {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3414 return NULL;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3415 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3416
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3417 fcf->enable = NGX_CONF_UNSET;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3418
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3419 return fcf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3420 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3421
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3422
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3423 static char *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3424 ngx_foo_init_conf(ngx_cycle_t cycle, void conf)
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3425 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3426 ngx_foo_conf_t *fcf = conf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3427
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3428 ngx_conf_init_value(fcf->enable, 0);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3429
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3430 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3431 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3432
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3433
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3434 static char *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3435 ngx_foo_enable(ngx_conf_t cf, void post, void *data)
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3436 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3437 ngx_flag_t *fp = data;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3438
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3439 if (*fp == 0) {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3440 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3441 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3442
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3443 ngx_log_error(NGX_LOG_NOTICE, cf->log, 0, "Foo Module is enabled");
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3444
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3445 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3446 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3447 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3448 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3449
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3450 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3451
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3452
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3453 <section name="Configuration Directives" id="config_directives">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3454
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3455 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3456 The <literal>ngx_command_t</literal> type defines a single configuration
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3457 directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3458 Each module that supports configuration provides an array of such structures
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3459 that describe how to process arguments and what handlers to call:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3460 <programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3461 typedef struct ngx_command_s ngx_command_t;
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3462
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3463 struct ngx_command_s {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3464 ngx_str_t name;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3465 ngx_uint_t type;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3466 char (set)(ngx_conf_t cf, ngx_command_t cmd, void *conf);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3467 ngx_uint_t conf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3468 ngx_uint_t offset;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3469 void *post;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3470 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3471 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3472 Terminate the array with the special value <literal>ngx_null_command</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3473 The <literal>name</literal> is the name of a directive as it appears
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3474 in the configuration file, for example "worker_processes" or "listen".
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3475 The <literal>type</literal> is a bit-field of flags that specify the number of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3476 arguments the directive takes, its type, and the context in which it appears.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3477 The flags are:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3478
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3479 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3480
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3481 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3482 <literal>NGX_CONF_NOARGS</literal> — Directive takes no arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3483 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3484
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3485 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3486 <literal>NGX_CONF_1MORE</literal> — Directive takes one or more arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3487 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3488
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3489 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3490 <literal>NGX_CONF_2MORE</literal> — Directive takes two or more arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3491 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3492
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3493 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3494 <literal>NGX_CONF_TAKE1</literal>..<literal>NGX_CONF_TAKE7</literal> —
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3495 Directive takes exactly the indicated number of arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3496 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3497
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3498 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3499 <literal>NGX_CONF_TAKE12</literal>, <literal>NGX_CONF_TAKE13</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3500 <literal>NGX_CONF_TAKE23</literal>, <literal>NGX_CONF_TAKE123</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3501 <literal>NGX_CONF_TAKE1234</literal> — Directive may take different number of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3502 arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3503 Options are limited to the given numbers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3504 For example, <literal>NGX_CONF_TAKE12</literal> means it takes one or two
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3505 arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3506 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3507
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3508 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3509
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3510 The flags for directive types are:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3511
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3512 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3513
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3514 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3515 <literal>NGX_CONF_BLOCK</literal> — Directive is a block, that is, it can
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3516 contain other directives within its opening and closing curly braces, or even
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3517 implement its own parser to handle contents inside.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3518 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3519
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3520 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3521 <literal>NGX_CONF_FLAG</literal> — Directive takes a boolean value, either
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3522 <literal>on</literal> or <literal>off</literal>.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3523 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3524
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3525 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3526
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3527 A directive's context defines where it may appear in the configuration:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3528
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3529 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3530
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3531 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3532 <literal>NGX_MAIN_CONF</literal> — In the top level context.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3533 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3534
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3535 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3536 <literal>NGX_HTTP_MAIN_CONF</literal> — In the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3537 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3538
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3539 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3540 <literal>NGX_HTTP_SRV_CONF</literal> — In a <literal>server</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3541 within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3542 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3543
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3544 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3545 <literal>NGX_HTTP_LOC_CONF</literal> — In a <literal>location</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3546 within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3547 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3548
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3549 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3550 <literal>NGX_HTTP_UPS_CONF</literal> — In an <literal>upstream</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3551 within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3552 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3553
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3554 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3555 <literal>NGX_HTTP_SIF_CONF</literal> — In an <literal>if</literal> block within
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3556 a <literal>server</literal> block in the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3557 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3558
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3559 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3560 <literal>NGX_HTTP_LIF_CONF</literal> — In an <literal>if</literal> block within
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3561 a <literal>location</literal> block in the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3562 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3563
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3564 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3565 <literal>NGX_HTTP_LMT_CONF</literal> — In a <literal>limit_except</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3566 block within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3567 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3568
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3569 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3570 <literal>NGX_STREAM_MAIN_CONF</literal> — In the <literal>stream</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3571 block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3572 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3573
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3574 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3575 <literal>NGX_STREAM_SRV_CONF</literal> — In a <literal>server</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3576 within the <literal>stream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3577 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3578
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3579 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3580 <literal>NGX_STREAM_UPS_CONF</literal> — In an <literal>upstream</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3581 within the <literal>stream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3582 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3583
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3584 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3585 <literal>NGX_MAIL_MAIN_CONF</literal> — In the <literal>mail</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3586 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3587
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3588 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3589 <literal>NGX_MAIL_SRV_CONF</literal> — In a <literal>server</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3590 within the <literal>mail</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3591 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3592
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3593 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3594 <literal>NGX_EVENT_CONF</literal> — In the <literal>event</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3595 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3596
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3597 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3598 <literal>NGX_DIRECT_CONF</literal> — Used by modules that don't
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3599 create a hierarchy of contexts and only have one global configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3600 This configuration is passed to the handler as the <literal>conf</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3601 argument.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3602 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3603 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3604
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3605 The configuration parser uses these flags to throw an error in case of
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3606 a misplaced directive and calls directive handlers supplied with a proper
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3607 configuration pointer, so that the same directives in different locations can
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3608 store their values in distinct places.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3609 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3610
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3611 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3612 The <literal>set</literal> field defines a handler that processes a directive
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3613 and stores parsed values into the corresponding configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3614 There's a number of functions that perform common conversions:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3615
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3616 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3617
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3618 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3619 <literal>ngx_conf_set_flag_slot</literal> — Converts the literal strings
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3620 <literal>on</literal> and <literal>off</literal> into an
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3621 <literal>ngx_flag_t</literal> value with values 1 or 0, respectively.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3622 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3623
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3624 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3625 <literal>ngx_conf_set_str_slot</literal> — Stores a string as a value of the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3626 <literal>ngx_str_t</literal> type.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3627 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3628
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3629 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3630 <literal>ngx_conf_set_str_array_slot</literal> — Appends a value to an array
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3631 <literal>ngx_array_t</literal> of strings <literal>ngx_str_t</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3632 The array is created if does not already exist.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3633 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3634
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3635 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3636 <literal>ngx_conf_set_keyval_slot</literal> — Appends a key-value pair to an
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3637 array <literal>ngx_array_t</literal> of key-value pairs
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3638 <literal>ngx_keyval_t</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3639 The first string becomes the key and the second the value.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3640 The array is created if it does not already exist.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3641 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3642
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3643 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3644 <literal>ngx_conf_set_num_slot</literal> — Converts a directive's argument
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3645 to an <literal>ngx_int_t</literal> value.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3646 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3647
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3648 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3649 <literal>ngx_conf_set_size_slot</literal> — Converts a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3650 <link doc="../syntax.xml">size</link> to a <literal>size_t</literal> value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3651 expressed in bytes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3652 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3653
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3654 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3655 <literal>ngx_conf_set_off_slot</literal> — Converts an
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3656 <link doc="../syntax.xml">offset</link> to an <literal>off_t</literal> value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3657 expressed in bytes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3658 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3659
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3660 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3661 <literal>ngx_conf_set_msec_slot</literal> — Converts a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3662 <link doc="../syntax.xml">time</link> to an <literal>ngx_msec_t</literal> value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3663 expressed in milliseconds.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3664 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3665
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3666 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3667 <literal>ngx_conf_set_sec_slot</literal> — Converts a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3668 <link doc="../syntax.xml">time</link> to a <literal>time_t</literal> value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3669 expressed in in seconds.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3670 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3671
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3672 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3673 <literal>ngx_conf_set_bufs_slot</literal> — Converts the two supplied arguments
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3674 into an <literal>ngx_bufs_t</literal> object that holds the number and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3675 <link doc="../syntax.xml">size</link> of buffers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3676 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3677
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3678 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3679 <literal>ngx_conf_set_enum_slot</literal> — Converts the supplied argument
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3680 into an <literal>ngx_uint_t</literal> value.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3681 The null-terminated array of <literal>ngx_conf_enum_t</literal> passed in the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3682 <literal>post</literal> field defines the acceptable strings and corresponding
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3683 integer values.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3684 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3685
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3686 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3687 <literal>ngx_conf_set_bitmask_slot</literal> — Converts the supplied arguments
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3688 into an <literal>ngx_uint_t</literal> value.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3689 The mask values for each argument are ORed producing the result.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3690 The null-terminated array of <literal>ngx_conf_bitmask_t</literal> passed in the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3691 <literal>post</literal> field defines the acceptable strings and corresponding
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3692 mask values.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3693 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3694
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3695 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3696 <literal>set_path_slot</literal> — Converts the supplied arguments to an
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3697 <literal>ngx_path_t</literal> value and performs all required initializations.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3698 For details, see the documentation for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3699 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_temp_path">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3700 proxy_temp_path</link> directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3701 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3702
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3703 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3704 <literal>set_access_slot</literal> — Converts the supplied arguments to a file
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3705 permissions mask.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3706 For details, see the documentation for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3707 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_store_access">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3708 proxy_store_access</link> directive.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3709 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3710
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3711 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3712
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3713 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3714
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3715 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3716 The <literal>conf</literal> field defines which configuration structure is
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3717 passed to the directory handler.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3718 Core modules only have the global configuration and set
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3719 <literal>NGX_DIRECT_CONF</literal> flag to access it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3720 Modules like HTTP, Stream or Mail create hierarchies of configurations.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3721 For example, a module's configuration is created for <literal>server</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3722 <literal>location</literal> and <literal>if</literal> scopes.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3723
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3724 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3725 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3726 <literal>NGX_HTTP_MAIN_CONF_OFFSET</literal> — Configuration for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3727 <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3728 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3729
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3730 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3731 <literal>NGX_HTTP_SRV_CONF_OFFSET</literal> — Configuration for a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3732 <literal>server</literal> block within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3733 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3734
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3735 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3736 <literal>NGX_HTTP_LOC_CONF_OFFSET</literal> — Configuration for a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3737 <literal>location</literal> block within the <literal>http</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3738 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3739
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3740 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3741 <literal>NGX_STREAM_MAIN_CONF_OFFSET</literal> — Configuration for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3742 <literal>stream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3743 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3744
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3745 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3746 <literal>NGX_STREAM_SRV_CONF_OFFSET</literal> — Configuration for a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3747 <literal>server</literal> block within the <literal>stream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3748 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3749
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3750 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3751 <literal>NGX_MAIL_MAIN_CONF_OFFSET</literal> — Configuration for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3752 <literal>mail</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3753 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3754
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3755 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3756 <literal>NGX_MAIL_SRV_CONF_OFFSET</literal> — Configuration for a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3757 <literal>server</literal> block within the <literal>mail</literal> block.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3758 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3759
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3760 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3761
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3762 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3763
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3764 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3765 The <literal>offset</literal> defines the offset of a field in a module
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3766 configuration structure that holds values for this particular directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3767 The typical use is to employ the <literal>offsetof()</literal> macro.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3768 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3769
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3770 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3771 The <literal>post</literal> field has two purposes: it may be used to define
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3772 a handler to be called after the main handler has completed, or to pass
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3773 additional data to the main handler.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3774 In the first case, the <literal>ngx_conf_post_t</literal> structure needs to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3775 be initialized with a pointer to the handler, for example:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3776 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3777 static char ngx_do_foo(ngx_conf_t cf, void post, void data);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3778 static ngx_conf_post_t ngx_foo_post = { ngx_do_foo };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3779 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3780 The <literal>post</literal> argument is the <literal>ngx_conf_post_t</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3781 object itself, and the <literal>data</literal> is a pointer to the value,
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3782 converted from arguments by the main handler with the appropriate type.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3783 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3784
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3785 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3786
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3787 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3788
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3789
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3790 <section name="HTTP" id="http">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3791
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3792
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3793 <section name="Connection" id="http_connection">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3794
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3795 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3796 Each HTTP client connection runs through the following stages:
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3797 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3798
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3799 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3800
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3801 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3802 <literal>ngx_event_accept()</literal> accepts a client TCP connection.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3803 This handler is called in response to a read notification on a listen socket.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3804 A new <literal>ngx_connecton_t</literal> object is created at this stage
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3805 to wrap the newly accepted client socket.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3806 Each nginx listener provides a handler to pass the new connection object to.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3807 For HTTP connections it's <literal>ngx_http_init_connection(c)</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3808 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3809
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3810 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3811 <literal>ngx_http_init_connection()</literal> performs early initialization of
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3812 the HTTP connection.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3813 At this stage an <literal>ngx_http_connection_t</literal> object is created for
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3814 the connection and its reference is stored in the connection's
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3815 <literal>data</literal> field.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3816 Later it will be replaced by an HTTP request object.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3817 A PROXY protocol parser and the SSL handshake are started at
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3818 this stage as well.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3819 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3820
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3821 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3822 <literal>ngx_http_wait_request_handler()</literal> read event handler
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3823 is called when data is available on the client socket.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3824 At this stage an HTTP request object <literal>ngx_http_request_t</literal> is
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3825 created and set to the connection's <literal>data</literal> field.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3826 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3827
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3828 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3829 <literal>ngx_http_process_request_line()</literal> read event handler
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3830 reads client request line.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3831 The handler is set by <literal>ngx_http_wait_request_handler()</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3832 The data is read into connection's <literal>buffer</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3833 The size of the buffer is initially set by the directive
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3834 <link doc="../http/ngx_http_core_module.xml" id="client_header_buffer_size"/>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3835 The entire client header is supposed to fit in the buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3836 If the initial size is not sufficient, a bigger buffer is allocated,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3837 with the capacity set by the <literal>large_client_header_buffers</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3838 directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3839 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3840
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3841 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3842 <literal>ngx_http_process_request_headers()</literal> read event handler,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3843 is set after <literal>ngx_http_process_request_line()</literal> to read
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3844 the client request header.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3845 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3846
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3847 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3848 <literal>ngx_http_core_run_phases()</literal> is called when the request header
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3849 is completely read and parsed.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3850 This function runs request phases from
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3851 <literal>NGX_HTTP_POST_READ_PHASE</literal> to
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3852 <literal>NGX_HTTP_CONTENT_PHASE</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3853 The last phase is intended to generate a response and pass it along the filter
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3854 chain.
1979 ff28ca78bef3 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1976 diff changeset	3855 The response is not necessarily sent to the client at this phase.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3856 It might remain buffered and be sent at the finalization stage.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3857 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3858
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3859 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3860 <literal>ngx_http_finalize_request()</literal> is usually called when the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3861 request has generated all the output or produced an error.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3862 In the latter case an appropriate error page is looked up and used as the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3863 response.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3864 If the response is not completely sent to the client by this point, an
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3865 HTTP writer <literal>ngx_http_writer()</literal> is activated to finish
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3866 sending outstanding data.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3867 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3868
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3869 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3870 <literal>ngx_http_finalize_connection()</literal> is called when the complete
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3871 response has been sent to the client and the request can be destroyed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3872 If the client connection keepalive feature is enabled,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3873 <literal>ngx_http_set_keepalive()</literal> is called, which destroys the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3874 current request and waits for the next request on the connection.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3875 Otherwise, <literal>ngx_http_close_request()</literal> destroys both the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3876 request and the connection.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3877 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3878
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3879 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3880
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3881 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3882
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3883
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3884 <section name="Request" id="http_request">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3885
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3886 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3887 For each client HTTP request the <literal>ngx_http_request_t</literal> object is
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3888 created. Some of the fields of this object are:
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3889 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3890
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3891 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3892
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3893 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3894
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3895 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3896 <literal>connection</literal> — Pointer to a <literal>ngx_connection_t</literal>
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3897 client connection object.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3898 Several requests can reference the same connection object at the same time -
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3899 one main request and its subrequests.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3900 After a request is deleted, a new request can be created on the same connection.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3901 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3902
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3903 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3904 Note that for HTTP connections <literal>ngx_connection_t</literal>'s
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3905 <literal>data</literal> field points back to the request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3906 Such requests are called active, as opposed to the other requests tied to the
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3907 connection.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3908 An active request is used to handle client connection events and is allowed to
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3909 output its response to the client.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3910 Normally, each request becomes active at some point so that it can send its
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3911 output.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3912 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3913
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3914 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3915
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3916 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3917
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3918 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3919 <literal>ctx</literal> — Array of HTTP module contexts.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3920 Each module of type <literal>NGX_HTTP_MODULE</literal> can store any value
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3921 (normally, a pointer to a structure) in the request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3922 The value is stored in the <literal>ctx</literal> array at the module's
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3923 <literal>ctx_index</literal> position.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3924 The following macros provide a convenient way to get and set request contexts:
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3925 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3926
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3927 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3928
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3929 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3930 <literal>ngx_http_get_module_ctx(r, module)</literal> — Returns
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3931 the <literal>module</literal>'s context
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3932 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3933
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3934 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3935 <literal>ngx_http_set_ctx(r, c, module)</literal> — Sets <literal>c</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3936 as the <literal>module</literal>'s context
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3937 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3938
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3939 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3940
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3941 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3942
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3943 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3944 <literal>main_conf</literal>, <literal>srv_conf</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3945 <literal>loc_conf</literal> — Arrays of current request
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3946 configurations.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3947 Configurations are stored at the module's <literal>ctx_index</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3948 positions.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3949 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3950
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3951 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3952 <literal>read_event_handler</literal>, <literal>write_event_handler</literal> -
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3953 Read and write event handlers for the request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3954 Normally, both the read and write event handlers for an HTTP connection
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3955 are set to <literal>ngx_http_request_handler()</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3956 This function calls the <literal>read_event_handler</literal> and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3957 <literal>write_event_handler</literal> handlers for the currently
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3958 active request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3959 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3960
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3961 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3962 <literal>cache</literal> — Request cache object for caching the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3963 upstream response.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3964 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3965
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3966 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3967 <literal>upstream</literal> — Request upstream object for proxying.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3968 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3969
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3970 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3971 <literal>pool</literal> — Request pool.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3972 The request object itself is allocated in this pool, which is destroyed when
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3973 the request is deleted.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3974 For allocations that need to be available throughout the client connection's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3975 lifetime, use <literal>ngx_connection_t</literal>'s pool instead.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3976 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3977
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3978 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3979 <literal>header_in</literal> — Buffer into which the client HTTP request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3980 header is read.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3981 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3982
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3983 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3984 <literal>headers_in</literal>, <literal>headers_out</literal> — Input and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3985 output HTTP headers objects.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3986 Both objects contain the <literal>headers</literal> field of type
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3987 <literal>ngx_list_t</literal> for keeping the raw list of headers.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3988 In addition to that, specific headers are available for getting and setting as
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3989 separate fields, for example <literal>content_length_n</literal>,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3990 <literal>status</literal> etc.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3991 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3992
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3993 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3994 <literal>request_body</literal> — Client request body object.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3995 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3996
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3997 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3998 <literal>start_sec</literal>, <literal>start_msec</literal> — Time point when
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3999 the request was created, used for tracking request duration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4000 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4001
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4002 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4003 <literal>method</literal>, <literal>method_name</literal> — Numeric and text
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4004 representation of the client HTTP request method.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4005 Numeric values for methods are defined in
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4006 <literal>src/http/ngx_http_request.h</literal> with the macros
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4007 <literal>NGX_HTTP_GET</literal>, <literal>NGX_HTTP_HEAD</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4008 <literal>NGX_HTTP_POST</literal>, etc.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4009 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4010
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4011 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4012 <literal>http_protocol</literal> — Client HTTP protocol version in its
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4013 original text form (“HTTP/1.0”, “HTTP/1.1” etc).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4014 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4015
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4016 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4017 <literal>http_version</literal> — Client HTTP protocol version in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4018 numeric form (<literal>NGX_HTTP_VERSION_10</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4019 <literal>NGX_HTTP_VERSION_11</literal>, etc.).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4020 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4021
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4022 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4023 <literal>http_major</literal>, <literal>http_minor</literal> — Client HTTP
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4024 protocol version in numeric form split into major and minor parts.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4025 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4026
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4027 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4028 <literal>request_line</literal>, <literal>unparsed_uri</literal> — Request line
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4029 and URI in the original client request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4030 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4031
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4032 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4033 <literal>uri</literal>, <literal>args</literal>, <literal>exten</literal> —
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4034 URI, arguments and file extension for the current request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4035 The URI value here might differ from the original URI sent by the client due to
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4036 normalization.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4037 Throughout request processing, these values can change as internal redirects
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4038 are performed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4039 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4040
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4041 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4042 <literal>main</literal> — Pointer to a main request object.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4043 This object is created to process a client HTTP request, as opposed to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4044 subrequests, which are created to perform a specific subtask within the main
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4045 request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4046 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4047
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4048 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4049 <literal>parent</literal> — Pointer to the parent request of a subrequest.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4050 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4051
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4052 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4053 <literal>postponed</literal> — List of output buffers and subrequests, in the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4054 order in which they are sent and created.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4055 The list is used by the postpone filter to provide consistent request output
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4056 when parts of it are created by subrequests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4057 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4058
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4059 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4060 <literal>post_subrequest</literal> — Pointer to a handler with the context
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4061 to be called when a subrequest gets finalized.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4062 Unused for main requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4063 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4064
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4065 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4066
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4067 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4068 <literal>posted_requests</literal> — List of requests to be started or
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4069 resumed, which is done by calling the request's
1932 937e03180281 Fixed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1929 diff changeset	4070 <literal>write_event_handler</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4071 Normally, this handler holds the request main function, which at first runs
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4072 request phases and then produces the output.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4073 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4074
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4075 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4076 A request is usually posted by the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4077 <literal>ngx_http_post_request(r, NULL)</literal> call.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4078 It is always posted to the main request <literal>posted_requests</literal> list.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4079 The function <literal>ngx_http_run_posted_requests(c)</literal> runs all
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4080 requests that are posted in the main request of the passed
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4081 connection's active request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4082 All event handlers call <literal>ngx_http_run_posted_requests</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4083 which can lead to new posted requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4084 Normally, it is called after invoking a request's read or write handler.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4085 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4086
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4087 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4088
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4089 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4090 <literal>phase_handler</literal> — Index of current request phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4091 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4092
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4093 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4094 <literal>ncaptures</literal>, <literal>captures</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4095 <literal>captures_data</literal> — Regex captures produced
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4096 by the last regex match of the request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4097 A regex match can occur at a number of places during request processing:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4098 map lookup, server lookup by SNI or HTTP Host, rewrite, proxy_redirect, etc.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4099 Captures produced by a lookup are stored in the above mentioned fields.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4100 The field <literal>ncaptures</literal> holds the number of captures,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4101 <literal>captures</literal> holds captures boundaries and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4102 <literal>captures_data</literal> holds the string against which the regex was
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4103 matched and which is used to extract captures.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4104 After each new regex match, request captures are reset to hold new values.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4105 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4106
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4107 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4108 <literal>count</literal> — Request reference counter.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4109 The field only makes sense for the main request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4110 Increasing the counter is done by simple <literal>r->main->count++</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4111 To decrease the counter, call
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4112 <literal>ngx_http_finalize_request(r, rc)</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4113 Creating of a subrequest and running the request body read process both
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4114 increment the counter.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4115 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4116
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4117 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4118 <literal>subrequests</literal> — Current subrequest nesting level.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4119 Each subrequest inherits its parent's nesting level, decreased by one.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4120 An error is generated if the value reaches zero.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4121 The value for the main request is defined by the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4122 <literal>NGX_HTTP_MAX_SUBREQUESTS</literal> constant.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4123 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4124
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4125 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4126 <literal>uri_changes</literal> — Number of URI changes remaining for
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4127 the request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4128 The total number of times a request can change its URI is limited by the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4129 <literal>NGX_HTTP_MAX_URI_CHANGES</literal> constant.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4130 With each change the value is decremented until it reaches zero, at which time
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4131 an error is generated.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4132 Rewrites and internal redirects to normal or named locations are considered URI
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4133 changes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4134 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4135
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4136 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4137 <literal>blocked</literal> — Counter of blocks held on the request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4138 While this value is non-zero, the request cannot be terminated.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4139 Currently, this value is increased by pending AIO operations (POSIX AIO and
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4140 thread operations) and active cache lock.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4141 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4142
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4143 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4144 <literal>buffered</literal> — Bitmask showing which modules have buffered the
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4145 output produced by the request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4146 A number of filters can buffer output; for example, sub_filter can buffer data
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4147 because of a partial string match, copy filter can buffer data because of the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4148 lack of free output buffers etc.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4149 As long as this value is non-zero, the request is not finalized
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4150 pending the flush.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4151 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4152
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4153 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4154 <literal>header_only</literal> — Flag indicating that the output does not
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4155 require a body.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4156 For example, this flag is used by HTTP HEAD requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4157 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4158
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4159 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4160 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4161 <literal>keepalive</literal> — Flag indicating whether client connection
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4162 keepalive is supported.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4163 The value is inferred from the HTTP version and the value of the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4164 <header>Connection</header> header.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4165 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4166 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4167
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4168 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4169 <literal>header_sent</literal> — Flag indicating that the output header
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4170 has already been sent by the request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4171 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4172
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4173 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4174 <literal>internal</literal> — Flag indicating that the current request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4175 is internal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4176 To enter the internal state, a request must pass through an internal
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4177 redirect or be a subrequest.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4178 Internal requests are allowed to enter internal locations.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4179 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4180
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4181 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4182 <literal>allow_ranges</literal> — Flag indicating that a partial response
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4183 can be sent to the client, as requested by the HTTP Range header.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4184 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4185
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4186 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4187 <literal>subrequest_ranges</literal> — Flag indicating that a partial response
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4188 can be sent while a subrequest is being processed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4189 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4190
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4191 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4192 <literal>single_range</literal> — Flag indicating that only a single continuous
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4193 range of output data can be sent to the client.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4194 This flag is usually set when sending a stream of data, for example from a
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4195 proxied server, and the entire response is not available in one buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4196 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4197
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4198 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4199 <literal>main_filter_need_in_memory</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4200 <literal>filter_need_in_memory</literal> — Flags
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4201 requesting that the output produced in memory buffers rather than files.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4202 This is a signal to the copy filter to read data from file buffers even if
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4203 sendfile is enabled.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4204 The difference between the two flags is the location of the filter modules that
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4205 set them.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4206 Filters called before the postpone filter in the filter chain set
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4207 <literal>filter_need_in_memory</literal>, requesting that only the current
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4208 request output come in memory buffers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4209 Filters called later in the filter chain set
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4210 <literal>main_filter_need_in_memory</literal>, requesting that
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4211 both the main request and all subrequests read files in memory
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4212 while sending output.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4213 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4214
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4215 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4216 <literal>filter_need_temporary</literal> — Flag requesting that the request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4217 output be produced in temporary buffers, but not in readonly memory buffers or
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4218 file buffers.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4219 This is used by filters which may change output directly in the buffers where
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4220 it's sent.</listitem>
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4221
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4222 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4223
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4224 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4225
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4226
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4227 <section name="Configuration" id="http_conf">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4228
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4229 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4230 Each HTTP module can have three types of configuration:
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4231 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4232
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4233 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4234
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4235 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4236 Main configuration — Applies to the entire <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4237 Functions as global settings for a module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4238 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4239
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4240 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4241 Server configuration — Applies to a single <literal>server</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4242 Functions as server-specific settings for a module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4243 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4244
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4245 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4246 Location configuration — Applies to a single <literal>location</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4247 <literal>if</literal> or <literal>limit_except</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4248 Functions as location-specific settings for a module.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4249 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4250
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4251 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4252
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4253 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4254 Configuration structures are created at the nginx configuration stage by
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4255 calling functions, which allocate the structures, initialize them
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4256 and merge them.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4257 The following example shows how to create a simple location
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4258 configuration for a module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4259 The configuration has one setting, <literal>foo</literal>, of type
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4260 unsigned integer.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4261 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4262
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4263 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4264 typedef struct {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4265 ngx_uint_t foo;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4266 } ngx_http_foo_loc_conf_t;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4267
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4268
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4269 static ngx_http_module_t ngx_http_foo_module_ctx = {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4270 NULL, /* preconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4271 NULL, /* postconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4272
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4273 NULL, /* create main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4274 NULL, /* init main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4275
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4276 NULL, /* create server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4277 NULL, /* merge server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4278
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4279 ngx_http_foo_create_loc_conf, /* create location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4280 ngx_http_foo_merge_loc_conf /* merge location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4281 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4282
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4283
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4284 static void *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4285 ngx_http_foo_create_loc_conf(ngx_conf_t *cf)
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4286 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4287 ngx_http_foo_loc_conf_t *conf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4288
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4289 conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_foo_loc_conf_t));
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4290 if (conf == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4291 return NULL;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4292 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4293
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4294 conf->foo = NGX_CONF_UNSET_UINT;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4295
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4296 return conf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4297 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4298
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4299
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4300 static char *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4301 ngx_http_foo_merge_loc_conf(ngx_conf_t cf, void parent, void *child)
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4302 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4303 ngx_http_foo_loc_conf_t *prev = parent;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4304 ngx_http_foo_loc_conf_t *conf = child;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4305
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4306 ngx_conf_merge_uint_value(conf->foo, prev->foo, 1);
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4307 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4308 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4309
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4310 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4311 As seen in the example, the <literal>ngx_http_foo_create_loc_conf()</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4312 function creates a new configuration structure, and
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4313 <literal>ngx_http_foo_merge_loc_conf()</literal> merges a configuration with
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4314 configuration from a higher level.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4315 In fact, server and location configuration do not exist only at the server and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4316 location levels, but are also created for all levels above them.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4317 Specifically, a server configuration is also created at the main level and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4318 location configurations are created at the main, server, and location levels.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4319 These configurations make it possible to specify server- and location-specific
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4320 settings at any level of an nginx configuration file.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4321 Eventually configurations are merged down.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4322 A number of macros like <literal>NGX_CONF_UNSET</literal> and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4323 <literal>NGX_CONF_UNSET_UINT</literal> are provided
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4324 for indicating a missing setting and ignoring it while merging.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4325 Standard nginx merge macros like <literal>ngx_conf_merge_value()</literal> and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4326 <literal>ngx_conf_merge_uint_value()</literal> provide a convenient way to
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4327 merge a setting and set the default value if none of the configurations
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4328 provided an explicit value.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4329 For complete list of macros for different types, see
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4330 <literal>src/core/ngx_conf_file.h</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4331 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4332
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4333 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4334 The following macros are available.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4335 for accessing configuration for HTTP modules at configuration time.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4336 They all take <literal>ngx_conf_t</literal> reference as the first argument.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4337 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4338
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4339 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4340
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4341 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4342 <literal>ngx_http_conf_get_module_main_conf(cf, module)</literal>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4343 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4344
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4345 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4346 <literal>ngx_http_conf_get_module_srv_conf(cf, module)</literal>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4347 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4348
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4349 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4350 <literal>ngx_http_conf_get_module_loc_conf(cf, module)</literal>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4351 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4352
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4353 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4354
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4355 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4356 The following example gets a pointer to a location configuration of
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4357 standard nginx core module
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4358 <link doc="../http/ngx_http_core_module.xml">ngx_http_core_module</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4359 and replaces the location content handler kept
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4360 in the <literal>handler</literal> field of the structure.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4361 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4362
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4363 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4364 static ngx_int_t ngx_http_foo_handler(ngx_http_request_t *r);
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4365
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4366
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4367 static ngx_command_t ngx_http_foo_commands[] = {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4368
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4369 { ngx_string("foo"),
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4370 NGX_HTTP_LOC_CONF\|NGX_CONF_NOARGS,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4371 ngx_http_foo,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4372 0,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4373 0,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4374 NULL },
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4375
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4376 ngx_null_command
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4377 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4378
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4379
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4380 static char *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4381 ngx_http_foo(ngx_conf_t cf, ngx_command_t cmd, void *conf)
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4382 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4383 ngx_http_core_loc_conf_t *clcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4384
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4385 clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4386 clcf->handler = ngx_http_bar_handler;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4387
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4388 return NGX_CONF_OK;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4389 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4390 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4391
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4392 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4393 The following macros are available for accessing configuration for HTTP
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4394 modules at runtime.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4395 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4396
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4397 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4398
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4399 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4400 <literal>ngx_http_get_module_main_conf(r, module)</literal>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4401 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4402
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4403 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4404 <literal>ngx_http_get_module_srv_conf(r, module)</literal>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4405 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4406
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4407 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4408 <literal>ngx_http_get_module_loc_conf(r, module)</literal>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4409 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4410
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4411 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4412
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4413 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4414 These macros receive a reference to an HTTP request
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4415 <literal>ngx_http_request_t</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4416 The main configuration of a request never changes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4417 Server configuration can change from the default after
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4418 the virtual server for the request is chosen.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4419 Location configuration selected for processing a request can change multiple
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4420 times as a result of a rewrite operation or internal redirect.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4421 The following example shows how to access a module's HTTP configuration at
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4422 runtime.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4423 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4424
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4425 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4426 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4427 ngx_http_foo_handler(ngx_http_request_t *r)
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4428 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4429 ngx_http_foo_loc_conf_t *flcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4430
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4431 flcf = ngx_http_get_module_loc_conf(r, ngx_http_foo_module);
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4432
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4433 ...
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4434 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4435 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4436
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4437 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4438
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4439
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4440 <section name="Phases" id="http_phases">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4441
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4442 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4443 Each HTTP request passes through a sequence of phases.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4444 In each phase a distinct type of processing is performed on the request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4445 Module-specific handlers can be registered in most phases,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4446 and many standard nginx modules register their phase handlers as a way
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4447 to get called at a specific stage of request processing.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4448 Phases are processed successively and the phase handlers are called
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4449 once the request reaches the phase.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4450 Following is the list of nginx HTTP phases.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4451 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4452
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4453 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4454
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4455 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4456 <literal>NGX_HTTP_POST_READ_PHASE</literal> — First phase.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4457 The <link doc="../http/ngx_http_realip_module.xml">ngx_http_realip_module</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4458 registers its handler at this phase to enable
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4459 substitution of client addresses before any other module is invoked.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4460 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4461
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4462 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4463 <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal> — Phase where
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4464 rewrite directives defined in a <literal>server</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4465 (but outside a <literal>location</literal> block) are processed.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4466 The
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4467 <link doc="../http/ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4468 installs its handler at this phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4469 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4470
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4471 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4472 <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> — Special phase
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4473 where a location is chosen based on the request URI.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4474 Before this phase, the default location for the relevant virtual server
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4475 is assigned to the request, and any module requesting a location configuration
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4476 receives the configuration for the default server location.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4477 This phase a assigns a new location to the request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4478 No additional handlers can be registered at this phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4479 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4480
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4481 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4482 <literal>NGX_HTTP_REWRITE_PHASE</literal> — Same as
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4483 <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal>, but for
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4484 rewrite rules defined in the location, chosen in the previous phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4485 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4486
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4487 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4488 <literal>NGX_HTTP_POST_REWRITE_PHASE</literal> — Special phase
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4489 where the request is redirected to a new location if its URI changed
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4490 during a rewrite.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4491 This is implemented by the request going through
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4492 the <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> again.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4493 No additional handlers can be registered at this phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4494 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4495
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4496 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4497 <literal>NGX_HTTP_PREACCESS_PHASE</literal> — A common phase for different
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4498 types of handlers, not associated with access control.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4499 The standard nginx modules
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4500 <link doc="../http/ngx_http_limit_conn_module.xml">ngx_http_limit_conn_module
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4501 </link> and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4502 <link doc="../http/ngx_http_limit_req_module.xml">
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4503 ngx_http_limit_req_module</link> register their handlers at this phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4504 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4505
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4506 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4507 <literal>NGX_HTTP_ACCESS_PHASE</literal> — Phase where it is verified
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4508 that the client is authorized to make the request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4509 Standard nginx modules such as
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4510 <link doc="../http/ngx_http_access_module.xml">ngx_http_access_module</link> and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4511 <link doc="../http/ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4512 </link> register their handlers at this phase.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4513 By default the client must pass the authorization check of all handlers
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4514 registered at this phase for the request to continue to the next phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4515 The <link doc="../http/ngx_http_core_module.xml" id="satisfy"/> directive,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4516 can be used to permit processing to continue if any of the phase handlers
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4517 authorizes the client.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4518 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4519
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4520 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4521 <literal>NGX_HTTP_POST_ACCESS_PHASE</literal> — Special phase where the
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4522 <link doc="../http/ngx_http_core_module.xml" id="satisfy">satisfy any</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4523 directive is processed.
2146 c07cd947402f Development guide: typo fixed. Andrei Belov <defan@nginx.com> parents: 2081 diff changeset	4524 If some access phase handlers denied access and none explicitly allowed it, the
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4525 request is finalized.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4526 No additional handlers can be registered at this phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4527 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4528
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4529 <listitem>
2024 a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4530 <literal>NGX_HTTP_PRECONTENT_PHASE</literal> — Phase for handlers to be called
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4531 prior to generating content.
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4532 Standard modules such as
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4533 <link doc="../http/ngx_http_core_module.xml" id="try_files">
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4534 ngx_http_try_files_module</link> and
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4535 <link doc="../http/ngx_http_mirror_module.xml">ngx_http_mirror_module</link>
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4536 register their handlers at this phase.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4537 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4538
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4539 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4540 <literal>NGX_HTTP_CONTENT_PHASE</literal> — Phase where the response
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4541 is normally generated.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4542 Multiple nginx standard modules register their handlers at this phase,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4543 including
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4544 <link doc="../http/ngx_http_index_module.xml">ngx_http_index_module</link> or
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4545 <literal>ngx_http_static_module</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4546 They are called sequentially until one of them produces
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4547 the output.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4548 It's also possible to set content handlers on a per-location basis.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4549 If the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4550 <link doc="../http/ngx_http_core_module.xml">ngx_http_core_module</link>'s
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4551 location configuration has <literal>handler</literal> set, it is
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4552 called as the content handler and the handlers installed at this phase
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4553 are ignored.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4554 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4555
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4556 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4557 <literal>NGX_HTTP_LOG_PHASE</literal> — Phase where request logging
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4558 is performed.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4559 Currently, only the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4560 <link doc="../http/ngx_http_log_module.xml">ngx_http_log_module</link>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4561 registers its handler
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4562 at this stage for access logging.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4563 Log phase handlers are called at the very end of request processing, right
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4564 before freeing the request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4565 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4566
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4567 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4568
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4569 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4570 Following is the example of a preaccess phase handler.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4571 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4572
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4573 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4574 static ngx_http_module_t ngx_http_foo_module_ctx = {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4575 NULL, /* preconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4576 ngx_http_foo_init, /* postconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4577
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4578 NULL, /* create main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4579 NULL, /* init main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4580
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4581 NULL, /* create server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4582 NULL, /* merge server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4583
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4584 NULL, /* create location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4585 NULL /* merge location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4586 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4587
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4588
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4589 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4590 ngx_http_foo_handler(ngx_http_request_t *r)
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4591 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4592 ngx_str_t *ua;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4593
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4594 ua = r->headers_in->user_agent;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4595
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4596 if (ua == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4597 return NGX_DECLINED;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4598 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4599
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4600 /* reject requests with "User-Agent: foo" */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4601 if (ua->value.len == 3 && ngx_strncmp(ua->value.data, "foo", 3) == 0) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4602 return NGX_HTTP_FORBIDDEN;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4603 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4604
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4605 return NGX_DECLINED;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4606 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4607
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4608
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4609 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4610 ngx_http_foo_init(ngx_conf_t *cf)
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4611 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4612 ngx_http_handler_pt *h;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4613 ngx_http_core_main_conf_t *cmcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4614
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4615 cmcf = ngx_http_conf_get_module_main_conf(cf, ngx_http_core_module);
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4616
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4617 h = ngx_array_push(&cmcf->phases[NGX_HTTP_PREACCESS_PHASE].handlers);
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4618 if (h == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4619 return NGX_ERROR;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4620 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4621
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4622 *h = ngx_http_foo_handler;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4623
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4624 return NGX_OK;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4625 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4626 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4627
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4628 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4629 Phase handlers are expected to return specific codes:
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4630 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4631
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4632 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4633
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4634 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4635 <literal>NGX_OK</literal> — Proceed to the next phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4636 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4637
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4638 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4639 <literal>NGX_DECLINED</literal> — Proceed to the next handler of the current
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4640 phase.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4641 If the current handler is the last in the current phase,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4642 move to the next phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4643 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4644
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4645 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4646 <literal>NGX_AGAIN</literal>, <literal>NGX_DONE</literal> — Suspend
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4647 phase handling until some future event which can be
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4648 an asynchronous I/O operation or just a delay, for example.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4649 It is assumed, that phase handling will be resumed later by calling
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4650 <literal>ngx_http_core_run_phases()</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4651 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4652
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4653 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4654 Any other value returned by the phase handler is treated as a request
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4655 finalization code, in particular, an HTTP response code.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4656 The request is finalized with the code provided.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4657 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4658
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4659 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4660
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4661 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4662 For some phases, return codes are treated in a slightly different way.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4663 At the content phase, any return code other that
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4664 <literal>NGX_DECLINED</literal> is considered a finalization code.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4665 Any return code from the location content handlers is considered a
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4666 finalization code.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4667 At the access phase, in
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4668 <link doc="../http/ngx_http_core_module.xml" id="satisfy">satisfy any</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4669 mode,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4670 any return code other than <literal>NGX_OK</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4671 <literal>NGX_DECLINED</literal>, <literal>NGX_AGAIN</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4672 <literal>NGX_DONE</literal> is considered a denial.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4673 If no subsequent access handlers allow or deny access with a different
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4674 code, the denial code will become the finalization code.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4675 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4676
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4677 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4678
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	4679
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4680 <section name="Variables" id="http_variables">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4681
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4682 <section name="Accessing existing variables" id="http_existing_variables">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4683
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4684 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4685 Variables can be referenced by index (this is the most common method)
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4686 or name (see <link id="http_creating_variables">below</link>).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4687 The index is created at configuration stage, when a variable is added
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4688 to the configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4689 To obtain the variable index, use
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4690 <literal>ngx_http_get_variable_index()</literal>:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4691 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4692 ngx_str_t name; /* ngx_string("foo") */
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4693 ngx_int_t index;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4694
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4695 index = ngx_http_get_variable_index(cf, &name);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4696 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4697 Here, <literal>cf</literal> is a pointer to nginx configuration and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4698 <literal>name</literal> points to a string containing the variable name.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4699 The function returns <literal>NGX_ERROR</literal> on error or a valid index
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4700 otherwise, which is typically stored somewhere in the module's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4701 configuration for future use.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4702 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4703
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4704 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4705 All HTTP variables are evaluated in the context of a given HTTP request,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4706 and results are specific to and cached in that HTTP request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4707 All functions that evaluate variables return the
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4708 <literal>ngx_http_variable_value_t</literal> type, representing
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4709 the variable value:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4710 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4711 typedef ngx_variable_value_t ngx_http_variable_value_t;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4712
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4713 typedef struct {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4714 unsigned len:28;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4715
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4716 unsigned valid:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4717 unsigned no_cacheable:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4718 unsigned not_found:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4719 unsigned escape:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4720
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4721 u_char *data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4722 } ngx_variable_value_t;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4723 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4724 where:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4725 <list type="bullet">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4726
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4727 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4728 <literal>len</literal> — The length of the value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4729 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4730
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4731 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4732 <literal>data</literal> — The value itself
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4733 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4734
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4735 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4736 <literal>valid</literal> — The value is valid
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4737 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4738
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4739 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4740 <literal>not_found</literal> — The variable was not found and thus
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4741 the <literal>data</literal> and <literal>len</literal> fields are irrelevant;
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4742 this can happen, for example, with variables like <var>$arg_foo</var>
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4743 when a corresponding argument was not passed in a request
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4744 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4745
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4746 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4747 <literal>no_cacheable</literal> — Do not cache result
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4748 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4749
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4750 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4751 <literal>escape</literal> — Used internally by the logging module to mark
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4752 values that require escaping on output.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4753 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4754
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4755 </list>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4756 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4757
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4758 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4759 The <literal>ngx_http_get_flushed_variable()</literal>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4760 and <literal>ngx_http_get_indexed_variable()</literal> functions
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4761 are used to obtain the value of a variable.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4762 They have the same interface - accepting an HTTP request <literal>r</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4763 as a context for evaluating the variable and an <literal>index</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4764 that identifies it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4765 An example of typical usage:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4766 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4767 ngx_http_variable_value_t *v;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4768
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4769 v = ngx_http_get_flushed_variable(r, index);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4770
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4771 if (v == NULL \|\| v->not_found) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4772 /* we failed to get value or there is no such variable, handle it */
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4773 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4774 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4775
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4776 /* some meaningful value is found */
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4777 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4778 The difference between functions is that the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4779 <literal>ngx_http_get_indexed_variable()</literal> returns a cached value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4780 and <literal>ngx_http_get_flushed_variable()</literal> flushes the cache for
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4781 non-cacheable variables.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4782 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4783
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4784 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4785 Some modules, such as SSI and Perl, need to deal with variables for which the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4786 name is not known at configuration time.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4787 An index therefore cannot be used to access them, but the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4788 <literal>ngx_http_get_variable(r, name, key)</literal> function
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4789 is available.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4790 It searches for a variable with a given
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4791 <literal>name</literal> and its hash <literal>key</literal> derived
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4792 from the name.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4793 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4794
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4795 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4796
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4797
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4798 <section name="Creating variables" id="http_creating_variables">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4799
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4800 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4801 To create a variable, use the <literal>ngx_http_add_variable()</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4802 function.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4803 It takes as arguments a configuration (where the variable is registered),
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4804 the variable name and flags that control the function's behaviour:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4805
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4806 <list type="bullet">
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4807 <listitem><literal>NGX_HTTP_VAR_CHANGEABLE</literal> — Enables redefinition of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4808 the variable: there is no conflict if another module defines a variable with
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4809 the same name.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4810 This allows the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4811 <link doc="../http/ngx_http_rewrite_module.xml" id="set"/> directive
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4812 to override variables.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4813 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4814
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4815 <listitem><literal>NGX_HTTP_VAR_NOCACHEABLE</literal> — Disables caching,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4816 which is useful for variables such as <literal>$time_local</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4817 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4818
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4819 <listitem><literal>NGX_HTTP_VAR_NOHASH</literal> — Indicates that
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4820 this variable is only accessible by index, not by name.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4821 This is a small optimization for use when it is known that the
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4822 variable is not needed in modules like SSI or Perl.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4823 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4824
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4825 <listitem><literal>NGX_HTTP_VAR_PREFIX</literal> — The name of the
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4826 variable is a prefix.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4827 In this case, a handler must implement additional logic to obtain the value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4828 of a specific variable.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4829 For example, all “<literal>arg_</literal>” variables are processed by the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4830 same handler, which performs lookup in request arguments and returns the value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4831 of a specific argument.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4832 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4833
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4834 </list>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4835
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4836 The function returns NULL in case of error or a pointer to
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4837 <literal>ngx_http_variable_t</literal> otherwise:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4838 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4839 struct ngx_http_variable_s {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4840 ngx_str_t name;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4841 ngx_http_set_variable_pt set_handler;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4842 ngx_http_get_variable_pt get_handler;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4843 uintptr_t data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4844 ngx_uint_t flags;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4845 ngx_uint_t index;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4846 };
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4847 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4848
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4849 The <literal>get</literal> and <literal>set</literal> handlers
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4850 are called to obtain or set the variable value,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4851 <literal>data</literal> is passed to variable handlers, and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4852 <literal>index</literal> holds assigned variable index used to reference
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4853 the variable.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4854 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4855
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4856 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4857 Usually, a null-terminated static array of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4858 <literal>ngx_http_variable_t</literal> structures is created
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4859 by a module and processed at the preconfiguration stage to add variables
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4860 into the configuration, for example:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4861 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4862 static ngx_http_variable_t ngx_http_foo_vars[] = {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4863
2009 9b7302e3b21f DevGuide: fixed variables example. Vladimir Homutov <vl@nginx.com> parents: 2008 diff changeset	4864 { ngx_string("foo_v1"), NULL, ngx_http_foo_v1_variable, 0, 0, 0 },
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4865
2023 ec34516cbd1b DevGuide: documented macros for null variables. Vladimir Homutov <vl@nginx.com> parents: 2009 diff changeset	4866 ngx_http_null_variable
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4867 };
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4868
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4869 static ngx_int_t
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4870 ngx_http_foo_add_variables(ngx_conf_t *cf)
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4871 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4872 ngx_http_variable_t var, v;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4873
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4874 for (v = ngx_http_foo_vars; v->name.len; v++) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4875 var = ngx_http_add_variable(cf, &v->name, v->flags);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4876 if (var == NULL) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4877 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4878 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4879
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4880 var->get_handler = v->get_handler;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4881 var->data = v->data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4882 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4883
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4884 return NGX_OK;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4885 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4886 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4887 This function in the example is used to initialize
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4888 the <literal>preconfiguration</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4889 field of the HTTP module context and is called before the parsing of HTTP
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4890 configuration, so that the parser can refer to these variables.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4891 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4892
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4893 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4894 The <literal>get</literal> handler is responsible for evaluating a variable
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4895 in the context of a specific request, for example:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4896 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4897 static ngx_int_t
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4898 ngx_http_variable_connection(ngx_http_request_t *r,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4899 ngx_http_variable_value_t *v, uintptr_t data)
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4900 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4901 u_char *p;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4902
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4903 p = ngx_pnalloc(r->pool, NGX_ATOMIC_T_LEN);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4904 if (p == NULL) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4905 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4906 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4907
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4908 v->len = ngx_sprintf(p, "%uA", r->connection->number) - p;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4909 v->valid = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4910 v->no_cacheable = 0;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4911 v->not_found = 0;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4912 v->data = p;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4913
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4914 return NGX_OK;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4915 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4916 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4917 It returns <literal>NGX_ERROR</literal> in case of internal error
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4918 (for example, failed memory allocation) or <literal>NGX_OK</literal> otherwise.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4919 To learn the status of variable evaluation, inspect the flags
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4920 in <literal>ngx_http_variable_value_t</literal> (see the description
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4921 <link id="http_existing_variables">above</link>).
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4922 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4923
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4924 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4925 The <literal>set</literal> handler allows setting the property
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4926 referenced by the variable.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4927 For example, the set handler of the <literal>$limit_rate</literal> variable
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4928 modifies the request's <literal>limit_rate</literal> field:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4929 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4930 ...
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4931 { ngx_string("limit_rate"), ngx_http_variable_request_set_size,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4932 ngx_http_variable_request_get_size,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4933 offsetof(ngx_http_request_t, limit_rate),
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4934 NGX_HTTP_VAR_CHANGEABLE\|NGX_HTTP_VAR_NOCACHEABLE, 0 },
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4935 ...
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4936
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4937 static void
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4938 ngx_http_variable_request_set_size(ngx_http_request_t *r,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4939 ngx_http_variable_value_t *v, uintptr_t data)
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4940 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4941 ssize_t s, *sp;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4942 ngx_str_t val;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4943
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4944 val.len = v->len;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4945 val.data = v->data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4946
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4947 s = ngx_parse_size(&val);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4948
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4949 if (s == NGX_ERROR) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4950 ngx_log_error(NGX_LOG_ERR, r->connection->log, 0,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4951 "invalid size \"%V\"", &val);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4952 return;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4953 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4954
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4955 sp = (ssize_t ) ((char ) r + data);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4956
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4957 *sp = s;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4958
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4959 return;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4960 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4961 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4962
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4963 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4964
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4965 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4966
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4967 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4968
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4969
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4970 <section name="Complex values" id="http_complex_values">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4971
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4972 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4973 A complex value, despite its name, provides an easy way to evaluate
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4974 expressions which can contain text, variables, and their combination.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4975 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4976
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4977 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4978 The complex value description in
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4979 <literal>ngx_http_compile_complex_value</literal> is compiled at the
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4980 configuration stage into <literal>ngx_http_complex_value_t</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4981 which is used at runtime to obtain results of expression evaluation.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4982
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4983 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4984 ngx_str_t *value;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4985 ngx_http_complex_value_t cv;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4986 ngx_http_compile_complex_value_t ccv;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4987
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4988 value = cf->args->elts; /* directive arguments */
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4989
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4990 ngx_memzero(&ccv, sizeof(ngx_http_compile_complex_value_t));
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4991
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4992 ccv.cf = cf;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4993 ccv.value = &value[1];
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4994 ccv.complex_value = &cv;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4995 ccv.zero = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4996 ccv.conf_prefix = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4997
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4998 if (ngx_http_compile_complex_value(&ccv) != NGX_OK) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4999 return NGX_CONF_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5000 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5001 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5002
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5003 Here, <literal>ccv</literal> holds all parameters that are required to
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5004 initialize the complex value <literal>cv</literal>:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5005
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5006 <list type="bullet">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5007
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5008 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5009 <literal>cf</literal> — Configuration pointer
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5010 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5011
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5012 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5013 <literal>value</literal> — String to be parsed (input)
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5014 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5015
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5016 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5017 <literal>complex_value</literal> — Compiled value (output)
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5018 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5019
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5020 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5021 <literal>zero</literal> — Flag that enables zero-terminating value
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5022 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5023
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5024 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5025 <literal>conf_prefix</literal> — Prefixes the result with the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5026 configuration prefix (the directory where nginx is currently looking for
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5027 configuration)
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5028 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5029
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5030 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5031 <literal>root_prefix</literal> — Prefixes the result with the root prefix
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5032 (the normal nginx installation prefix)
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5033 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5034
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5035 </list>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5036 The <literal>zero</literal> flag is useful when results are to be passed to
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5037 libraries that require zero-terminated strings, and prefixes are handy when
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5038 dealing with filenames.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5039 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5040
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5041 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5042 Upon successful compilation, <literal>cv.lengths</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5043 contains information about the presence of variables
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5044 in the expression.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5045 The NULL value means that the expression contained static text only,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5046 and so can be stored in a simple string rather than as a complex value.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5047 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5048
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5049 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5050 The <literal>ngx_http_set_complex_value_slot()</literal> is a convenient
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5051 function used to initialize a complex value completely in the directive
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5052 declaration itself.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5053 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5054
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5055 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5056 At runtime, a complex value can be calculated using the
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5057 <literal>ngx_http_complex_value()</literal> function:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5058 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5059 ngx_str_t res;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5060
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5061 if (ngx_http_complex_value(r, &cv, &res) != NGX_OK) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5062 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5063 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5064 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5065 Given the request <literal>r</literal> and previously compiled
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5066 value <literal>cv</literal>, the function evaluates the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5067 expression and writes the result to <literal>res</literal>.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5068 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5069
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5070 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5071
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5072
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5073 <section name="Request redirection" id="http_request_redirection">
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5074
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5075 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5076 An HTTP request is always connected to a location via the
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5077 <literal>loc_conf</literal> field of the <literal>ngx_http_request_t</literal>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5078 structure.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5079 This means that at any point the location configuration of any module can be
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5080 retrieved from the request by calling
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5081 <literal>ngx_http_get_module_loc_conf(r, module)</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5082 Request location can change several times during the request's lifetime.
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5083 Initially, a default server location of the default server is assigned to a
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5084 request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5085 If the request switches to a different server (chosen by the HTTP
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5086 <header>Host</header> header or SSL SNI extension), the request switches to the
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5087 default location of that server as well.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5088 The next change of the location takes place at the
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5089 <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> request phase.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5090 At this phase a location is chosen by request URI among all non-named locations
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5091 configured for the server.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5092 The
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5093 <link doc="../http/ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5094 can change the request URI at the
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5095 <literal>NGX_HTTP_REWRITE_PHASE</literal> request phase as a result of
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5096 the <link doc="../http/ngx_http_rewrite_module.xml" id="rewrite">rewrite</link>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5097 directive and send the request back
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5098 to the <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> phase for selection of a
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5099 new location based on the new URI.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5100 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5101
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5102 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5103 It is also possible to redirect a request to a new location at any point by
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5104 calling one of
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5105 <literal>ngx_http_internal_redirect(r, uri, args)</literal> or
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5106 <literal>ngx_http_named_location(r, name)</literal>.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5107 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5108
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5109 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5110 The <literal>ngx_http_internal_redirect(r, uri, args)</literal> function changes
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5111 the request URI and returns the request to the
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5112 <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal> phase.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5113 The request proceeds with a server default location.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5114 Later at <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> a new location is chosen
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5115 based on the new request URI.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5116 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5117
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5118 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5119 The following example performs an internal redirect with the new request
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5120 arguments.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5121 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5122
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5123 <programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5124 ngx_int_t
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5125 ngx_http_foo_redirect(ngx_http_request_t *r)
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5126 {
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5127 ngx_str_t uri, args;
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5128
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5129 ngx_str_set(&uri, "/foo");
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5130 ngx_str_set(&args, "bar=1");
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5131
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5132 return ngx_http_internal_redirect(r, &uri, &args);
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5133 }
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5134 </programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5135
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5136 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5137 The function <literal>ngx_http_named_location(r, name)</literal> redirects
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5138 a request to a named location. The name of the location is passed as the
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5139 argument.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5140 The location is looked up among all named locations of the current
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5141 server, after which the requests switches to the
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5142 <literal>NGX_HTTP_REWRITE_PHASE</literal> phase.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5143 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5144
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5145 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5146 The following example performs a redirect to a named location @foo.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5147 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5148
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5149 <programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5150 ngx_int_t
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5151 ngx_http_foo_named_redirect(ngx_http_request_t *r)
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5152 {
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5153 ngx_str_t name;
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5154
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5155 ngx_str_set(&name, "foo");
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5156
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5157 return ngx_http_named_location(r, &name);
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5158 }
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5159 </programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5160
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5161 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5162 Both functions - <literal>ngx_http_internal_redirect(r, uri, args)</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5163 and <literal>ngx_http_named_location(r, name)</literal> can be called when
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5164 nginx modules have already stored some contexts in a request's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5165 <literal>ctx</literal> field.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5166 It's possible for these contexts to become inconsistent with the new
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5167 location configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5168 To prevent inconsistency, all request contexts are
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5169 erased by both redirect functions.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5170 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5171
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5172 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5173 Calling <literal>ngx_http_internal_redirect(r, uri, args)</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5174 or <literal>ngx_http_named_location(r, name)</literal> increases the request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5175 <literal>count</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5176 For consistent request reference counting, call
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5177 <literal>ngx_http_finalize_request(r, NGX_DONE)</literal> after redirecting the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5178 request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5179 This will finalize current request code path and decrease the counter.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5180 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5181
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5182 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5183 Redirected and rewritten requests become internal and can access the
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5184 <link doc="../http/ngx_http_core_module.xml" id="internal">internal</link>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5185 locations.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5186 Internal requests have the <literal>internal</literal> flag set.
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5187 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5188
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5189 </section>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5190
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5191
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5192 <section name="Subrequests" id="http_subrequests">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5193
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5194 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5195 Subrequests are primarily used to insert output of one request into another,
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5196 possibly mixed with other data.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5197 A subrequest looks like a normal request, but shares some data with its parent.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5198 In particular, all fields related to client input are shared
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5199 because a subrequest does not receive any other input from the client.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5200 The request field <literal>parent</literal> for a subrequest contains a link
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5201 to its parent request and is NULL for the main request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5202 The field <literal>main</literal> contains a link to the main request in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5203 a group of requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5204 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5205
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5206 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5207 A subrequest starts in the <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5208 phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5209 It passes through the same subsequent phases as a normal request and is
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5210 assigned a location based on its own URI.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5211 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5212
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5213 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5214 The output header in a subrequest is always ignored.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5215 The <literal>ngx_http_postpone_filter</literal> places the subrequest's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5216 output body in the right position relative to other data produced
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5217 by the parent request.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5218 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5219
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5220 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5221 Subrequests are related to the concept of active requests.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5222 A request <literal>r</literal> is considered active if
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5223 <literal>c->data == r</literal>, where <literal>c</literal> is the client
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5224 connection object.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5225 At any given point, only the active request in a request group is allowed
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5226 to output its buffers to the client.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5227 An inactive request can still send its output to the filter chain, but it
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5228 does not pass beyond the <literal>ngx_http_postpone_filter</literal> and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5229 remains buffered by that filter until the request becomes active.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5230 Here are some rules of request activation:
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5231 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5232
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5233 <list type="bullet">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5234
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5235 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5236 Initially, the main request is active.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5237 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5238
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5239 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5240 The first subrequest of an active request becomes active right after creation.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5241 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5242
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5243 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5244 The <literal>ngx_http_postpone_filter</literal> activates the next request
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5245 in the active request's subrequest list, once all data prior to that request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5246 are sent.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5247 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5248
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5249 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5250 When a request is finalized, its parent is activated.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5251 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5252
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5253 </list>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5254
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5255 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5256 Create a subrequest by calling the function
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5257 <literal>ngx_http_subrequest(r, uri, args, psr, ps, flags)</literal>, where
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5258 <literal>r</literal> is the parent request, <literal>uri</literal> and
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5259 <literal>args</literal> are the URI and arguments of the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5260 subrequest, <literal>psr</literal> is the output parameter, which receives the
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5261 newly created subrequest reference, <literal>ps</literal> is a callback object
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5262 for notifying the parent request that the subrequest is being finalized, and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5263 <literal>flags</literal> is bitmask of flags.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5264 The following flags are available:
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5265 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5266
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5267 <list type="bullet">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5268
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5269 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5270 <literal>NGX_HTTP_SUBREQUEST_IN_MEMORY</literal> - Output is not
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5271 sent to the client, but rather stored in memory.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5272 The flag only affects subrequests which are processed by one of the proxying
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5273 modules.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5274 After a subrequest is finalized its output is available in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5275 a <literal>r->upstream->buffer</literal> of type <literal>ngx_buf_t</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5276 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5277
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5278 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5279 <literal>NGX_HTTP_SUBREQUEST_WAITED</literal> - The subrequest's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5280 <literal>done</literal> flag is set even if the subrequest is not active when
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5281 it is finalized.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5282 This subrequest flag is used by the SSI filter.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5283 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5284
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5285 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5286 <literal>NGX_HTTP_SUBREQUEST_CLONE</literal> - The subrequest is created as a
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5287 clone of its parent.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5288 It is started at the same location and proceeds from the same phase as the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5289 parent request.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5290 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5291
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5292 </list>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5293
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5294 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5295 The following example creates a subrequest with the URI
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5296 of <literal>/foo</literal>.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5297 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5298
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5299 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5300 ngx_int_t rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5301 ngx_str_t uri;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5302 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5303
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5304 ...
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5305
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5306 ngx_str_set(&uri, "/foo");
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5307
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5308 rc = ngx_http_subrequest(r, &uri, NULL, &sr, NULL, 0);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5309 if (rc == NGX_ERROR) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5310 /* error */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5311 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5312 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5313
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5314 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5315 This example clones the current request and sets a finalization callback for the
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5316 subrequest.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5317 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5318
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5319 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5320 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5321 ngx_http_foo_clone(ngx_http_request_t *r)
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5322 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5323 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5324 ngx_http_post_subrequest_t *ps;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5325
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5326 ps = ngx_palloc(r->pool, sizeof(ngx_http_post_subrequest_t));
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5327 if (ps == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5328 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5329 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5330
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5331 ps->handler = ngx_http_foo_subrequest_done;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5332 ps->data = "foo";
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5333
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5334 return ngx_http_subrequest(r, &r->uri, &r->args, &sr, ps,
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5335 NGX_HTTP_SUBREQUEST_CLONE);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5336 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5337
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5338
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5339 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5340 ngx_http_foo_subrequest_done(ngx_http_request_t r, void data, ngx_int_t rc)
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5341 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5342 char msg = (char ) data;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5343
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5344 ngx_log_error(NGX_LOG_INFO, r->connection->log, 0,
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5345 "done subrequest r:%p msg:%s rc:%i", r, msg, rc);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5346
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5347 return rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5348 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5349 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5350
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5351 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5352 Subrequests are normally created in a body filter, in which case their output
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5353 can be treated like the output from any explicit request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5354 This means that eventually the output of a subrequest is sent to the client,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5355 after all explicit buffers that are passed before subrequest creation and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5356 before any buffers that are passed after creation.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5357 This ordering is preserved even for large hierarchies of subrequests.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5358 The following example inserts output from a subrequest after all request data
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5359 buffers, but before the final buffer with the <literal>last_buf</literal> flag.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5360 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5361
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5362 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5363 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5364 ngx_http_foo_body_filter(ngx_http_request_t r, ngx_chain_t in)
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5365 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5366 ngx_int_t rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5367 ngx_buf_t *b;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5368 ngx_uint_t last;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5369 ngx_chain_t *cl, out;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5370 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5371 ngx_http_foo_filter_ctx_t *ctx;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5372
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5373 ctx = ngx_http_get_module_ctx(r, ngx_http_foo_filter_module);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5374 if (ctx == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5375 return ngx_http_next_body_filter(r, in);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5376 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5377
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5378 last = 0;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5379
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5380 for (cl = in; cl; cl = cl->next) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5381 if (cl->buf->last_buf) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5382 cl->buf->last_buf = 0;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5383 cl->buf->last_in_chain = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5384 cl->buf->sync = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5385 last = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5386 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5387 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5388
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5389 /* Output explicit output buffers */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5390
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5391 rc = ngx_http_next_body_filter(r, in);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5392
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5393 if (rc == NGX_ERROR \|\| !last) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5394 return rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5395 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5396
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5397 /*
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5398 * Create the subrequest. The output of the subrequest
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5399 * will automatically be sent after all preceding buffers,
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5400 * but before the last_buf buffer passed later in this function.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5401 */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5402
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5403 if (ngx_http_subrequest(r, ctx->uri, NULL, &sr, NULL, 0) != NGX_OK) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5404 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5405 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5406
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5407 ngx_http_set_ctx(r, NULL, ngx_http_foo_filter_module);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5408
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5409 /* Output the final buffer with the last_buf flag */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5410
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5411 b = ngx_calloc_buf(r->pool);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5412 if (b == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5413 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5414 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5415
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5416 b->last_buf = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5417
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5418 out.buf = b;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5419 out.next = NULL;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5420
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5421 return ngx_http_output_filter(r, &out);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5422 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5423 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5424
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5425 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5426 A subrequest can also be created for other purposes than data output.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5427 For example, the <link doc="../http/ngx_http_auth_request_module.xml">
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5428 ngx_http_auth_request_module</link> module
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5429 creates a subrequest at the <literal>NGX_HTTP_ACCESS_PHASE</literal> phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5430 To disable output at this point, the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5431 <literal>header_only</literal> flag is set on the subrequest.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5432 This prevents the subrequest body from being sent to the client.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5433 Note that the subrequest's header is never sent to the client.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5434 The result of the subrequest can be analyzed in the callback handler.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5435 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5436
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5437 </section>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5438
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5439
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5440 <section name="Request finalization" id="http_request_finalization">
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5441
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5442 <para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5443 An HTTP request is finalized by calling the function
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5444 <literal>ngx_http_finalize_request(r, rc)</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5445 It is usually finalized by the content handler after all output buffers
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5446 are sent to the filter chain.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5447 At this point all of the output might not be sent to the client,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5448 with some of it remaining buffered somewhere along the filter chain.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5449 If it is, the <literal>ngx_http_finalize_request(r, rc)</literal> function
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5450 automatically installs a special handler <literal>ngx_http_writer(r)</literal>
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5451 to finish sending the output.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5452 A request is also finalized in case of an error or if a standard HTTP response
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5453 code needs to be returned to the client.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5454 </para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5455
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5456 <para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5457 The function <literal>ngx_http_finalize_request(r, rc)</literal> expects the
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5458 following <literal>rc</literal> values:
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5459 </para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5460
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5461 <list type="bullet">
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5462
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5463 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5464 <literal>NGX_DONE</literal> - Fast finalization.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5465 Decrement the request <literal>count</literal> and destroy the request if it
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5466 reaches zero.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5467 The client connection can be used for more requests after the current request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5468 is destroyed.
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5469 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5470
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5471 <listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5472 <literal>NGX_ERROR</literal>, <literal>NGX_HTTP_REQUEST_TIME_OUT</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5473 (<literal>408</literal>), <literal>NGX_HTTP_CLIENT_CLOSED_REQUEST</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5474 (<literal>499</literal>) - Error finalization.
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5475 Terminate the request as soon as possible and close the client connection.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5476 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5477
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5478 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5479 <literal>NGX_HTTP_CREATED</literal> (<literal>201</literal>),
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5480 <literal>NGX_HTTP_NO_CONTENT</literal> (<literal>204</literal>), codes greater
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5481 than or equal to <literal>NGX_HTTP_SPECIAL_RESPONSE</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5482 (<literal>300</literal>) - Special response finalization.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5483 For these values nginx either sends to the client a default response page for
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5484 the code or performs the internal redirect to an
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5485 <link doc="../http/ngx_http_core_module.xml" id="error_page"/> location if that
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5486 is configured for the code.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5487 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5488
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5489 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5490 Other codes are considered successful finalization codes and might activate the
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5491 request writer to finish sending the response body.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5492 Once the body is completely sent, the request <literal>count</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5493 is decremented.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5494 If it reaches zero, the request is destroyed, but the client connection can
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5495 still be used for other requests.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5496 If <literal>count</literal> is positive, there are unfinished activities
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5497 within the request, which will be finalized at a later point.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5498 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5499
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5500 </list>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5501
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5502 </section>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5503
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5504
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5505 <section name="Request body" id="http_request_body">
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5506
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5507 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5508 For dealing with the body of a client request, nginx provides the
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5509 <literal>ngx_http_read_client_request_body(r, post_handler)</literal> and
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5510 <literal>ngx_http_discard_request_body(r)</literal> functions.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5511 The first function reads the request body and makes it available via the
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5512 <literal>request_body</literal> request field.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5513 The second function instructs nginx to discard (read and ignore) the request
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5514 body.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5515 One of these functions must be called for every request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5516 Normally, the content handler makes the call.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5517 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5518
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5519 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5520 Reading or discarding the client request body from a subrequest is not allowed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5521 It must always be done in the main request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5522 When a subrequest is created, it inherits the parent's
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5523 <literal>request_body</literal> object which can be used by the subrequest if
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5524 the main request has previously read the request body.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5525 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5526
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5527 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5528 The function
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5529 <literal>ngx_http_read_client_request_body(r, post_handler)</literal> starts
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5530 the process of reading the request body.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5531 When the body is completely read, the <literal>post_handler</literal> callback
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5532 is called to continue processing the request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5533 If the request body is missing or has already been read, the callback is called
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5534 immediately.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5535 The function
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5536 <literal>ngx_http_read_client_request_body(r, post_handler)</literal>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5537 allocates the <literal>request_body</literal> request field of type
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5538 <literal>ngx_http_request_body_t</literal>.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5539 The field <literal>bufs</literal> of this object keeps the result as a buffer
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5540 chain.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5541 The body can be saved in memory buffers or file buffers, if the capacity
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5542 specified by the
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5543 <link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5544 directive is not enough to fit the entire body in memory.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5545 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5546
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5547 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5548 The following example reads a client request body and returns its size.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5549 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5550
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5551 <programlisting>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5552 ngx_int_t
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5553 ngx_http_foo_content_handler(ngx_http_request_t *r)
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5554 {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5555 ngx_int_t rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5556
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5557 rc = ngx_http_read_client_request_body(r, ngx_http_foo_init);
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5558
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5559 if (rc >= NGX_HTTP_SPECIAL_RESPONSE) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5560 /* error */
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5561 return rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5562 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5563
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5564 return NGX_DONE;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5565 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5566
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5567
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5568 void
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5569 ngx_http_foo_init(ngx_http_request_t *r)
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5570 {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5571 off_t len;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5572 ngx_buf_t *b;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5573 ngx_int_t rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5574 ngx_chain_t *in, out;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5575
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5576 if (r->request_body == NULL) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5577 ngx_http_finalize_request(r, NGX_HTTP_INTERNAL_SERVER_ERROR);
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5578 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5579 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5580
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5581 len = 0;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5582
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5583 for (in = r->request_body->bufs; in; in = in->next) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5584 len += ngx_buf_size(in->buf);
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5585 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5586
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5587 b = ngx_create_temp_buf(r->pool, NGX_OFF_T_LEN);
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5588 if (b == NULL) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5589 ngx_http_finalize_request(r, NGX_HTTP_INTERNAL_SERVER_ERROR);
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5590 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5591 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5592
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5593 b->last = ngx_sprintf(b->pos, "%O", len);
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5594 b->last_buf = (r == r->main) ? 1: 0;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5595 b->last_in_chain = 1;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5596
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5597 r->headers_out.status = NGX_HTTP_OK;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5598 r->headers_out.content_length_n = b->last - b->pos;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5599
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5600 rc = ngx_http_send_header(r);
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5601
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5602 if (rc == NGX_ERROR \|\| rc > NGX_OK \|\| r->header_only) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5603 ngx_http_finalize_request(r, rc);
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5604 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5605 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5606
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5607 out.buf = b;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5608 out.next = NULL;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5609
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5610 rc = ngx_http_output_filter(r, &out);
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5611
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5612 ngx_http_finalize_request(r, rc);
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5613 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5614 </programlisting>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5615
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5616 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5617 The following fields of the request determine how the request body is read:
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5618 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5619
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5620 <list type="bullet">
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5621
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5622 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5623 <literal>request_body_in_single_buf</literal> - Read the body to a single memory
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5624 buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5625 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5626
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5627 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5628 <literal>request_body_in_file_only</literal> - Always read the body to a file,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5629 even if fits in the memory buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5630 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5631
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5632 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5633 <literal>request_body_in_persistent_file</literal> - Do not unlink the file
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5634 immediately after creation.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5635 A file with this flag can be moved to another directory.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5636 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5637
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5638 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5639 <literal>request_body_in_clean_file</literal> - Unlink the file when the
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5640 request is finalized.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5641 This can be useful when a file was supposed to be moved to another directory
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5642 but was not moved for some reason.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5643 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5644
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5645 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5646 <literal>request_body_file_group_access</literal> - Enable group access to the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5647 file by replacing the default 0600 access mask with 0660.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5648 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5649
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5650 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5651 <literal>request_body_file_log_level</literal> - Severity level at which to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5652 log file errors.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5653 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5654
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5655 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5656 <literal>request_body_no_buffering</literal> - Read the request body without
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5657 buffering.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5658 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5659
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5660 </list>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5661
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5662 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5663 The <literal>request_body_no_buffering</literal> flag enables the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5664 unbuffered mode of reading a request body.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5665 In this mode, after calling
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5666 <literal>ngx_http_read_client_request_body()</literal>, the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5667 <literal>bufs</literal> chain might keep only a part of the body.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5668 To read the next part, call the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5669 <literal>ngx_http_read_unbuffered_request_body(r)</literal> function.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5670 The return value <literal>NGX_AGAIN</literal> and the request flag
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5671 <literal>reading_body</literal> indicate that more data is available.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5672 If <literal>bufs</literal> is NULL after calling this function, there is
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5673 nothing to read at the moment.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5674 The request callback <literal>read_event_handler</literal> will be called when
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5675 the next part of request body is available.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5676 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5677
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5678 </section>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5679
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5680
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5681 <section name="Response" id="http_response">
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5682
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5683 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5684 In nginx an HTTP response is produced by sending the response header followed by
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5685 the optional response body.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5686 Both header and body are passed through a chain of filters and eventually get
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5687 written to the client socket.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5688 An nginx module can install its handler into the header or body filter chain
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5689 and process the output coming from the previous handler.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5690 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5691
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5692
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5693 <section name="Response header" id="http_response_header">
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5694
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5695 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5696 The <literal>ngx_http_send_header(r)</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5697 function sends the output header.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5698 Do not call this function until <literal>r->headers_out</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5699 contains all of the data required to produce the HTTP response header.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5700 The <literal>status</literal> field in <literal>r->headers_out</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5701 must always be set.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5702 If the response status indicates that a response body follows the header,
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5703 <literal>content_length_n</literal> can be set as well.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5704 The default value for this field is <literal>-1</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5705 which means that the body size is unknown.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5706 In this case, chunked transfer encoding is used.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5707 To output an arbitrary header, append the <literal>headers</literal> list.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5708 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5709
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5710 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5711 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5712 ngx_http_foo_content_handler(ngx_http_request_t *r)
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5713 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5714 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5715 ngx_table_elt_t *h;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5716
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5717 /* send header */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5718
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5719 r->headers_out.status = NGX_HTTP_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5720 r->headers_out.content_length_n = 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5721
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5722 /* X-Foo: foo */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5723
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5724 h = ngx_list_push(&r->headers_out.headers);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5725 if (h == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5726 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5727 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5728
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5729 h->hash = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5730 ngx_str_set(&h->key, "X-Foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5731 ngx_str_set(&h->value, "foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5732
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5733 rc = ngx_http_send_header(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5734
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5735 if (rc == NGX_ERROR \|\| rc > NGX_OK \|\| r->header_only) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5736 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5737 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5738
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5739 /* send body */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5740
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5741 ...
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5742 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5743 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5744
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5745 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5746
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5747
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5748 <section name="Header filters" id="http_header_filters">
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5749
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5750 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5751 The <literal>ngx_http_send_header(r)</literal> function invokes the header
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5752 filter chain by calling the first header filter handler stored in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5753 the <literal>ngx_http_top_header_filter</literal> variable.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5754 It's assumed that every header handler calls the next handler in the chain
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5755 until the final handler <literal>ngx_http_header_filter(r)</literal> is called.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5756 The final header handler constructs the HTTP response based on
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5757 <literal>r->headers_out</literal> and passes it to the
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5758 <literal>ngx_http_writer_filter</literal> for output.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5759 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5760
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5761 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5762 To add a handler to the header filter chain, store its address in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5763 the global variable <literal>ngx_http_top_header_filter</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5764 at configuration time.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5765 The previous handler address is normally stored in a static variable in a module
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5766 and is called by the newly added handler before exiting.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5767 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5768
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5769 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5770 The following example of a header filter module adds the HTTP header
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5771 "<literal>X-Foo: foo</literal>" to every response with status
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5772 <literal>200</literal>.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5773 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5774
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5775 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5776 #include <ngx_config.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5777 #include <ngx_core.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5778 #include <ngx_http.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5779
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5780
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5781 static ngx_int_t ngx_http_foo_header_filter(ngx_http_request_t *r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5782 static ngx_int_t ngx_http_foo_header_filter_init(ngx_conf_t *cf);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5783
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5784
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5785 static ngx_http_module_t ngx_http_foo_header_filter_module_ctx = {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5786 NULL, /* preconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5787 ngx_http_foo_header_filter_init, /* postconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5788
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5789 NULL, /* create main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5790 NULL, /* init main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5791
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5792 NULL, /* create server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5793 NULL, /* merge server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5794
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5795 NULL, /* create location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5796 NULL /* merge location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5797 };
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5798
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5799
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5800 ngx_module_t ngx_http_foo_header_filter_module = {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5801 NGX_MODULE_V1,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5802 &ngx_http_foo_header_filter_module_ctx, /* module context */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5803 NULL, /* module directives */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5804 NGX_HTTP_MODULE, /* module type */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5805 NULL, /* init master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5806 NULL, /* init module */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5807 NULL, /* init process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5808 NULL, /* init thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5809 NULL, /* exit thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5810 NULL, /* exit process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5811 NULL, /* exit master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5812 NGX_MODULE_V1_PADDING
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5813 };
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5814
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5815
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5816 static ngx_http_output_header_filter_pt ngx_http_next_header_filter;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5817
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5818
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5819 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5820 ngx_http_foo_header_filter(ngx_http_request_t *r)
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5821 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5822 ngx_table_elt_t *h;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5823
1971 5fb870087b76 Fixed typo and removed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1970 diff changeset	5824 /*
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5825 * The filter handler adds "X-Foo: foo" header
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5826 * to every HTTP 200 response
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5827 */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5828
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5829 if (r->headers_out.status != NGX_HTTP_OK) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5830 return ngx_http_next_header_filter(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5831 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5832
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5833 h = ngx_list_push(&r->headers_out.headers);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5834 if (h == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5835 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5836 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5837
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5838 h->hash = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5839 ngx_str_set(&h->key, "X-Foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5840 ngx_str_set(&h->value, "foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5841
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5842 return ngx_http_next_header_filter(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5843 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5844
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5845
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5846 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5847 ngx_http_foo_header_filter_init(ngx_conf_t *cf)
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5848 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5849 ngx_http_next_header_filter = ngx_http_top_header_filter;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5850 ngx_http_top_header_filter = ngx_http_foo_header_filter;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5851
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5852 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5853 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5854 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5855
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5856 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5857
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5858 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5859
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5860
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5861 <section name="Response body" id="http_response_body">
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5862
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5863 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5864 To send the response body, call the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5865 <literal>ngx_http_output_filter(r, cl)</literal> function.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5866 The function can be called multiple times.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5867 Each time, it sends a part of the response body in the form of a buffer chain.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5868 Set the <literal>last_buf</literal> flag in the last body buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5869 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5870
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5871 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5872 The following example produces a complete HTTP response with "foo" as its body.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5873 For the example to work as subrequest as well as a main request,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5874 the <literal>last_in_chain</literal> flag is set in the last buffer
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5875 of the output.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5876 The <literal>last_buf</literal> flag is set only for the main request because
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5877 the last buffer for a subrequest does not end the entire output.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5878 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5879
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5880 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5881 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5882 ngx_http_bar_content_handler(ngx_http_request_t *r)
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5883 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5884 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5885 ngx_buf_t *b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5886 ngx_chain_t out;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5887
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5888 /* send header */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5889
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5890 r->headers_out.status = NGX_HTTP_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5891 r->headers_out.content_length_n = 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5892
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5893 rc = ngx_http_send_header(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5894
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5895 if (rc == NGX_ERROR \|\| rc > NGX_OK \|\| r->header_only) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5896 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5897 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5898
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5899 /* send body */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5900
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5901 b = ngx_calloc_buf(r->pool);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5902 if (b == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5903 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5904 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5905
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5906 b->last_buf = (r == r->main) ? 1: 0;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5907 b->last_in_chain = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5908
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5909 b->memory = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5910
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5911 b->pos = (u_char *) "foo";
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5912 b->last = b->pos + 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5913
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5914 out.buf = b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5915 out.next = NULL;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5916
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5917 return ngx_http_output_filter(r, &out);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5918 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5919 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5920
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5921 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5922
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5923
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5924 <section name="Body filters" id="http_body_filters">
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5925
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5926 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5927 The function <literal>ngx_http_output_filter(r, cl)</literal> invokes the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5928 body filter chain by calling the first body filter handler stored in
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5929 the <literal>ngx_http_top_body_filter</literal> variable.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5930 It's assumed that every body handler calls the next handler in the chain until
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5931 the final handler <literal>ngx_http_write_filter(r, cl)</literal> is called.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5932 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5933
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5934 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5935 A body filter handler receives a chain of buffers.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5936 The handler is supposed to process the buffers and pass a possibly new chain to
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5937 the next handler.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5938 It's worth noting that the chain links <literal>ngx_chain_t</literal> of the
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5939 incoming chain belong to the caller, and must not be reused or changed.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5940 Right after the handler completes, the caller can use its output chain links
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5941 to keep track of the buffers it has sent.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5942 To save the buffer chain or to substitute some buffers before passing to the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5943 next filter, a handler needs to allocate its own chain links.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5944 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5945
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5946 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5947 Following is an example of a simple body filter that counts the number of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5948 bytes in the body.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5949 The result is available as the <literal>$counter</literal> variable which can be
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5950 used in the access log.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5951 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5952
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5953 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5954 #include <ngx_config.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5955 #include <ngx_core.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5956 #include <ngx_http.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5957
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5958
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5959 typedef struct {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5960 off_t count;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5961 } ngx_http_counter_filter_ctx_t;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5962
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5963
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5964 static ngx_int_t ngx_http_counter_body_filter(ngx_http_request_t *r,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5965 ngx_chain_t *in);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5966 static ngx_int_t ngx_http_counter_variable(ngx_http_request_t *r,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5967 ngx_http_variable_value_t *v, uintptr_t data);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5968 static ngx_int_t ngx_http_counter_add_variables(ngx_conf_t *cf);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5969 static ngx_int_t ngx_http_counter_filter_init(ngx_conf_t *cf);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5970
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5971
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5972 static ngx_http_module_t ngx_http_counter_filter_module_ctx = {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5973 ngx_http_counter_add_variables, /* preconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5974 ngx_http_counter_filter_init, /* postconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5975
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5976 NULL, /* create main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5977 NULL, /* init main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5978
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5979 NULL, /* create server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5980 NULL, /* merge server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5981
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5982 NULL, /* create location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5983 NULL /* merge location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5984 };
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5985
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5986
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5987 ngx_module_t ngx_http_counter_filter_module = {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5988 NGX_MODULE_V1,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5989 &ngx_http_counter_filter_module_ctx, /* module context */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5990 NULL, /* module directives */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5991 NGX_HTTP_MODULE, /* module type */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5992 NULL, /* init master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5993 NULL, /* init module */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5994 NULL, /* init process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5995 NULL, /* init thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5996 NULL, /* exit thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5997 NULL, /* exit process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5998 NULL, /* exit master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5999 NGX_MODULE_V1_PADDING
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6000 };
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6001
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6002
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6003 static ngx_http_output_body_filter_pt ngx_http_next_body_filter;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6004
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6005 static ngx_str_t ngx_http_counter_name = ngx_string("counter");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6006
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6007
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6008 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6009 ngx_http_counter_body_filter(ngx_http_request_t r, ngx_chain_t in)
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6010 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6011 ngx_chain_t *cl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6012 ngx_http_counter_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6013
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6014 ctx = ngx_http_get_module_ctx(r, ngx_http_counter_filter_module);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6015 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6016 ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_counter_filter_ctx_t));
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6017 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6018 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6019 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6020
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6021 ngx_http_set_ctx(r, ctx, ngx_http_counter_filter_module);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6022 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6023
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6024 for (cl = in; cl; cl = cl->next) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6025 ctx->count += ngx_buf_size(cl->buf);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6026 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6027
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6028 return ngx_http_next_body_filter(r, in);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6029 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6030
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6031
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6032 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6033 ngx_http_counter_variable(ngx_http_request_t r, ngx_http_variable_value_t v,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6034 uintptr_t data)
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6035 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6036 u_char *p;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6037 ngx_http_counter_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6038
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6039 ctx = ngx_http_get_module_ctx(r, ngx_http_counter_filter_module);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6040 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6041 v->not_found = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6042 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6043 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6044
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6045 p = ngx_pnalloc(r->pool, NGX_OFF_T_LEN);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6046 if (p == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6047 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6048 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6049
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6050 v->data = p;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6051 v->len = ngx_sprintf(p, "%O", ctx->count) - p;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6052 v->valid = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6053 v->no_cacheable = 0;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6054 v->not_found = 0;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6055
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6056 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6057 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6058
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6059
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6060 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6061 ngx_http_counter_add_variables(ngx_conf_t *cf)
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6062 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6063 ngx_http_variable_t *var;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6064
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6065 var = ngx_http_add_variable(cf, &ngx_http_counter_name, 0);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6066 if (var == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6067 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6068 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6069
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6070 var->get_handler = ngx_http_counter_variable;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6071
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6072 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6073 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6074
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6075
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6076 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6077 ngx_http_counter_filter_init(ngx_conf_t *cf)
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6078 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6079 ngx_http_next_body_filter = ngx_http_top_body_filter;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6080 ngx_http_top_body_filter = ngx_http_counter_body_filter;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6081
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6082 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6083 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6084 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6085
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6086 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6087
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6088
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6089 <section name="Building filter modules" id="http_building_filter_modules">
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6090
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6091 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6092 When writing a body or header filter, pay special attention to the filter's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6093 position in the filter order.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6094 There's a number of header and body filters registered by nginx standard
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6095 modules.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6096 The nginx standard modules register a number of head and body filters and it's
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6097 important to register a new filter module in the right place with respect to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6098 them.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6099 Normally, modules register filters in their postconfiguration handlers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6100 The order in which filters are called during processing is obviously the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6101 reverse of the order in which they are registered.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6102 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6103
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6104 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6105 For third-party filter modules nginx provides a special slot
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6106 <literal>HTTP_AUX_FILTER_MODULES</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6107 To register a filter module in this slot, set
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6108 the <literal>ngx_module_type</literal> variable to
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6109 <literal>HTTP_AUX_FILTER</literal> in the module's configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6110 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6111
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6112 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6113 The following example shows a filter module config file assuming
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6114 for a module with just
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6115 one source file, <literal>ngx_http_foo_filter_module.c</literal>.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6116 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6117
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6118 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6119 ngx_module_type=HTTP_AUX_FILTER
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6120 ngx_module_name=ngx_http_foo_filter_module
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6121 ngx_module_srcs="$ngx_addon_dir/ngx_http_foo_filter_module.c"
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6122
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6123 . auto/module
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6124 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6125
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6126 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6127
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6128
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6129 <section name="Buffer reuse" id="http_body_buffers_reuse">
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6130
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6131 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6132 When issuing or altering a stream of buffers, it's often desirable to reuse the
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6133 allocated buffers.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6134 A standard and widely adopted approach in nginx code is to keep
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6135 two buffer chains for this purpose:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6136 <literal>free</literal> and <literal>busy</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6137 The <literal>free</literal> chain keeps all free buffers,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6138 which can be reused.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6139 The <literal>busy</literal> chain keeps all buffers sent by the current
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6140 module that are still in use by some other filter handler.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6141 A buffer is considered in use if its size is greater than zero.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6142 Normally, when a buffer is consumed by a filter, its <literal>pos</literal>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6143 (or <literal>file_pos</literal> for a file buffer) is moved towards
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6144 <literal>last</literal> (<literal>file_last</literal> for a file buffer).
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6145 Once a buffer is completely consumed, it's ready to be reused.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6146 To add newly freed buffers to the <literal>free</literal> chain
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6147 it's enough to iterate over the <literal>busy</literal> chain and move the zero
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6148 size buffers at the head of it to <literal>free</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6149 This operation is so common that there is a special function for it,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6150 <literal>ngx_chain_update_chains(free, busy, out, tag)</literal>.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6151 The function appends the output chain <literal>out</literal> to
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6152 <literal>busy</literal> and moves free buffers from the top of
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6153 <literal>busy</literal> to <literal>free</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6154 Only the buffers with the specified <literal>tag</literal> are reused.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6155 This lets a module reuse only the buffers that it allocated itself.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6156 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6157
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6158 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6159 The following example is a body filter that inserts the string “foo” before each
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6160 incoming buffer.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6161 The new buffers allocated by the module are reused if possible.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6162 Note that for this example to work properly, setting up a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6163 <link id="http_header_filters">header filter</link>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6164 and resetting <literal>content_length_n</literal> to <literal>-1</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6165 is also required, but the relevant code is not provided here.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6166 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6167
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6168 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6169 typedef struct {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6170 ngx_chain_t *free;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6171 ngx_chain_t *busy;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6172 } ngx_http_foo_filter_ctx_t;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6173
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6174
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6175 ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6176 ngx_http_foo_body_filter(ngx_http_request_t r, ngx_chain_t in)
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6177 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6178 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6179 ngx_buf_t *b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6180 ngx_chain_t cl, tl, out, *ll;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6181 ngx_http_foo_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6182
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6183 ctx = ngx_http_get_module_ctx(r, ngx_http_foo_filter_module);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6184 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6185 ctx = ngx_pcalloc(r->pool, sizeof(ngx_http_foo_filter_ctx_t));
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6186 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6187 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6188 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6189
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6190 ngx_http_set_ctx(r, ctx, ngx_http_foo_filter_module);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6191 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6192
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6193 /* create a new chain "out" from "in" with all the changes */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6194
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6195 ll = &out;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6196
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6197 for (cl = in; cl; cl = cl->next) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6198
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6199 /* append "foo" in a reused buffer if possible */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6200
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6201 tl = ngx_chain_get_free_buf(r->pool, &ctx->free);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6202 if (tl == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6203 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6204 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6205
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6206 b = tl->buf;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6207 b->tag = (ngx_buf_tag_t) &ngx_http_foo_filter_module;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6208 b->memory = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6209 b->pos = (u_char *) "foo";
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6210 b->last = b->pos + 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6211
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6212 *ll = tl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6213 ll = &tl->next;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6214
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6215 /* append the next incoming buffer */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6216
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6217 tl = ngx_alloc_chain_link(r->pool);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6218 if (tl == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6219 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6220 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6221
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6222 tl->buf = cl->buf;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6223 *ll = tl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6224 ll = &tl->next;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6225 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6226
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6227 *ll = NULL;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6228
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6229 /* send the new chain */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6230
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6231 rc = ngx_http_next_body_filter(r, out);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6232
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6233 /* update "busy" and "free" chains for reuse */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6234
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6235 ngx_chain_update_chains(r->pool, &ctx->free, &ctx->busy, &out,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6236 (ngx_buf_tag_t) &ngx_http_foo_filter_module);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6237
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6238 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6239 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6240 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6241
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6242 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6243
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6244
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6245 <section name="Load balancing" id="http_load_balancing">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6246
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6247 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6248 The
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6249 <link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6250 provides the basic functionality needed to pass requests to remote servers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6251 Modules that implement specific protocols, such as HTTP or FastCGI, use
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6252 this functionality.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6253 The module also provides an interface for creating custom
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6254 load-balancing modules and implements a default round-robin method.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6255 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6256
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6257 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6258 The <link doc="../http/ngx_http_upstream_module.xml" id="least_conn"/>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6259 and <link doc="../http/ngx_http_upstream_module.xml" id="hash"/>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6260 modules implement alternative load-balancing methods, but
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6261 are actually implemented as extensions of the upstream round-robin
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6262 module and share a lot of code with it, such as the representation
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6263 of a server group.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6264 The <link doc="../http/ngx_http_upstream_module.xml" id="keepalive"/> module
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6265 is an independent module that extends upstream functionality.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6266 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6267
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6268 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6269 The
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6270 <link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6271 can be configured explicitly by placing the corresponding
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6272 <link doc="../http/ngx_http_upstream_module.xml" id="upstream"/> block into
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6273 the configuration file, or implicitly by using directives
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6274 such as <link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6275 that accept a URL that gets evaluated at some point into a list of servers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6276 The alternative load-balancing methods are available only with an explicit
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6277 upstream configuration.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6278 The upstream module configuration has its own directive context
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6279 <literal>NGX_HTTP_UPS_CONF</literal>.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6280 The structure is defined as follows:
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6281 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6282 struct ngx_http_upstream_srv_conf_s {
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6283 ngx_http_upstream_peer_t peer;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6284 void **srv_conf;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6285
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6286 ngx_array_t servers; / ngx_http_upstream_server_t */
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6287
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6288 ngx_uint_t flags;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6289 ngx_str_t host;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6290 u_char *file_name;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6291 ngx_uint_t line;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6292 in_port_t port;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6293 ngx_uint_t no_port; /* unsigned no_port:1 */
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6294
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6295 #if (NGX_HTTP_UPSTREAM_ZONE)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6296 ngx_shm_zone_t *shm_zone;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6297 #endif
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6298 };
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6299 </programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6300
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6301 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6302
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6303 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6304 <literal>srv_conf</literal> — Configuration context of upstream modules.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6305 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6306
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6307 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6308 <literal>servers</literal> — Array of
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6309 <literal>ngx_http_upstream_server_t</literal>, the result of parsing a set of
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6310 <link doc="../http/ngx_http_upstream_module.xml" id="server"/> directives
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6311 in the <literal>upstream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6312 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6313
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6314 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6315 <literal>flags</literal> — Flags that mostly mark which features
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6316 are supported by the load-balancing method.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6317 The features are configured as parameters of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6318 the <link doc="../http/ngx_http_upstream_module.xml" id="server"/> directive:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6319
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6320
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6321 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6322
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6323 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6324 <literal>NGX_HTTP_UPSTREAM_CREATE</literal> — Distinguishes explicitly
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6325 defined upstreams from those that are automatically created by the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6326 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/> directive
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6327 and “friends”
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6328 (FastCGI, SCGI, etc.)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6329 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6330
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6331 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6332 <literal>NGX_HTTP_UPSTREAM_WEIGHT</literal> — The “<literal>weight</literal>”
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6333 parameter is supported
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6334 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6335
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6336 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6337 <literal>NGX_HTTP_UPSTREAM_MAX_FAILS</literal> — The
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6338 “<literal>max_fails</literal>” parameter is supported
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6339 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6340
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6341 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6342 <literal>NGX_HTTP_UPSTREAM_FAIL_TIMEOUT</literal> —
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6343 The “<literal>fail_timeout</literal>” parameter is supported
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6344 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6345
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6346 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6347 <literal>NGX_HTTP_UPSTREAM_DOWN</literal> — The “<literal>down</literal>”
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6348 parameter is supported
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6349 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6350
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6351 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6352 <literal>NGX_HTTP_UPSTREAM_BACKUP</literal> — The “<literal>backup</literal>”
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6353 parameter is supported
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6354 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6355
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6356 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6357 <literal>NGX_HTTP_UPSTREAM_MAX_CONNS</literal> — The
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6358 “<literal>max_conns</literal>” parameter is supported
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6359 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6360
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6361 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6362
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6363 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6364
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6365 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6366 <literal>host</literal> — Name of the upstream.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6367 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6368
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6369 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6370 <literal>file_name, line</literal> — Name of the configuration file
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6371 and the line where the <literal>upstream</literal> block is located.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6372 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6373
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6374 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6375 <literal>port</literal> and <literal>no_port</literal> — Not used for
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6376 explicitly defined upstream groups.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6377 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6378
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6379 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6380 <literal>shm_zone</literal> — Shared memory zone used by this upstream group,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6381 if any.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6382 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6383
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6384 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6385 <literal>peer</literal> — object that holds generic methods for
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6386 initializing upstream configuration:
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6387
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6388 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6389 typedef struct {
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6390 ngx_http_upstream_init_pt init_upstream;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6391 ngx_http_upstream_init_peer_pt init;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6392 void *data;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6393 } ngx_http_upstream_peer_t;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6394 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6395 A module that implements a load-balancing algorithm must set these
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6396 methods and initialize private <literal>data</literal>.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6397 If <literal>init_upstream</literal> was not initialized during configuration
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6398 parsing, <literal>ngx_http_upstream_module</literal> sets it to the default
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6399 <literal>ngx_http_upstream_init_round_robin</literal> algorithm.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6400
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6401 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6402 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6403 <literal>init_upstream(cf, us)</literal> — Configuration-time
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6404 method responsible for initializing a group of servers and
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6405 initializing the <literal>init()</literal> method in case of success.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6406 A typical load-balancing module uses a list of servers in the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6407 <literal>upstream</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6408 to create an efficient data structure that it uses and saves its own
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6409 configuration to the <literal>data</literal> field.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6410 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6411
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6412 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6413 <literal>init(r, us)</literal> — Initializes a per-request
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6414 <literal>ngx_http_upstream_peer_t.peer</literal> structure that is used for
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6415 load balancing (not to be confused with the
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6416 <literal>ngx_http_upstream_srv_conf_t.peer</literal> described above which
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6417 is per-upstream).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6418 It is passed as the <literal>data</literal> argument to all callbacks that
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6419 deal with server selection.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6420 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6421 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6422
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6423 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6424 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6425 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6426
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6427 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6428 When nginx has to pass a request to another host for processing, it uses
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6429 the configured load-balancing method to obtain an address to connect to.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6430 The method is obtained from the
1994 effdf0747a05 Development guide: fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1993 diff changeset	6431 <literal>ngx_http_upstream_t.peer</literal> object
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6432 of type <literal>ngx_peer_connection_t</literal>:
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6433 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6434 struct ngx_peer_connection_s {
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6435 ...
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6436
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6437 struct sockaddr *sockaddr;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6438 socklen_t socklen;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6439 ngx_str_t *name;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6440
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6441 ngx_uint_t tries;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6442
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6443 ngx_event_get_peer_pt get;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6444 ngx_event_free_peer_pt free;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6445 ngx_event_notify_peer_pt notify;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6446 void *data;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6447
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6448 #if (NGX_SSL \|\| NGX_COMPAT)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6449 ngx_event_set_peer_session_pt set_session;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6450 ngx_event_save_peer_session_pt save_session;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6451 #endif
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6452
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6453 ...
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6454 };
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6455 </programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6456
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6457 The structure has the following fields:
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6458
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6459 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6460 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6461 <literal>sockaddr</literal>, <literal>socklen</literal>,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6462 <literal>name</literal> — Address of the upstream server to connect to;
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6463 this is the output parameter of a load-balancing method.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6464 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6465
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6466 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6467 <literal>data</literal> — The per-request data of a load-balancing method;
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6468 keeps the state of the selection algorithm and usually includes the link
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6469 to the upstream configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6470 It is passed as an argument to all methods that deal with server selection
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6471 (see <link id="lb_method_get">below</link>).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6472 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6473
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6474 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6475 <literal>tries</literal> — Allowed
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6476 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_next_upstream_tries">number</link>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6477 of attempts to connect to an upstream server.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6478 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6479
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6480 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6481 <literal>get</literal>, <literal>free</literal>, <literal>notify</literal>,
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6482 <literal>set_session</literal>, and <literal>save_session</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6483 - Methods of the load-balancing module, described below.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6484 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6485
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6486 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6487
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6488 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6489
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6490 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6491 All methods accept at least two arguments: a peer connection object
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6492 <literal>pc</literal> and the <literal>data</literal> created by
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6493 <literal>ngx_http_upstream_srv_conf_t.peer.init()</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6494 Note that it might differ from <literal>pc.data</literal> due
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6495 to “chaining” of load-balancing modules.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6496 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6497
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6498 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6499
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6500 <list type="bullet">
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6501 <listitem id="lb_method_get">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6502 <literal>get(pc, data)</literal> — The method called when the upstream
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6503 module is ready to pass a request to an upstream server and needs to know
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6504 its address.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6505 The method has to fill the <literal>sockaddr</literal>,
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6506 <literal>socklen</literal>, and <literal>name</literal> fields of
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6507 <literal>ngx_peer_connection_t</literal> structure.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6508 The return is one of:
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6509
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6510 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6511
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6512 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6513 <literal>NGX_OK</literal> — Server was selected.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6514 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6515
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6516 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6517 <literal>NGX_ERROR</literal> — Internal error occurred.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6518 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6519
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6520 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6521 <literal>NGX_BUSY</literal> — no servers are currently available.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6522 This can happen due to many reasons, including: the dynamic server group is
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6523 empty, all servers in the group are in the failed state, or
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6524 all servers in the group are already
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6525 handling the maximum number of connections.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6526 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6527
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6528 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6529 <literal>NGX_DONE</literal> — the underlying connection was reused and there
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6530 is no need to create a new connection to the upstream server.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6531 This value is set by the <literal>keepalive</literal> module.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6532 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6533
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6534 <!--
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6535 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6536 <literal>NGX_ABORT</literal> — the request was queued and the further
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6537 processing of this request should be postponed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6538 This value is set by the <literal>queue</literal> module.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6539 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6540 -->
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6541
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6542 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6543
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6544 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6545
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6546 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6547 <literal>free(pc, data, state)</literal> — The method called when an
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6548 upstream module has finished work with a particular server.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6549 The <literal>state</literal> argument is the completion status of the upstream
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6550 connection, a bitmask with the following possible values:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6551
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6552 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6553
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6554 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6555 <literal>NGX_PEER_FAILED</literal> — Attempt was
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6556 <link doc="../http/ngx_http_upstream_module.xml" id="max_fails">unsuccessful</link>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6557 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6558
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6559 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6560 <literal>NGX_PEER_NEXT</literal> — A special case when upstream server
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6561 returns codes <literal>403</literal> or <literal>404</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6562 which are not considered a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6563 <link doc="../http/ngx_http_upstream_module.xml" id="max_fails">failure</link>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6564 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6565
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6566 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6567 <literal>NGX_PEER_KEEPALIVE</literal> — Currently unused
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6568 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6569
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6570 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6571
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6572 This method also decrements the <literal>tries</literal> counter.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6573
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6574 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6575
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6576 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6577 <literal>notify(pc, data, type)</literal> — Currently unused
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6578 in the OSS version.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6579 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6580
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6581 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6582 <literal>set_session(pc, data)</literal> and
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6583 <literal>save_session(pc, data)</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6584 — SSL-specific methods that enable caching sessions to upstream
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6585 servers.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6586 The implementation is provided by the round-robin balancing method.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6587 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6588
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6589 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6590
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6591 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6592
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6593 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6594
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6595 </section>
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6596
2073 75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6597 <section name="Examples" id="examples">
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6598
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6599 <para>
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6600 The
2078 26e547b1022d DevGuide: changed nginx-dev-examples repository. Roman Arutyunyan <arut@nginx.com> parents: 2073 diff changeset	6601 <link url="http://hg.nginx.org/nginx-dev-examples">nginx-dev-examples</link>
2073 75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6602 repository provides nginx module examples.
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6603
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6604 </para>
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6605
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6606 </section>
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6607
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	6608 </article>

Mercurial > hg > nginx-site

annotate xml/en/docs/dev/development_guide.xml @ 2151:ed6b44206600