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

annotate xml/en/docs/dev/development_guide.xml @ 2277:4ad2cf470ed8

Updated OpenSSL and PCRE versions.

author	Yaroslav Zhuravlev <yar@nginx.com>
date	Thu, 15 Nov 2018 19:09:33 +0300
parents	2c8c10f00518
children	58df9b14b8ec

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"
2153 ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	12 rev="4">
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 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	737
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	738 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	739 The available string representations are:
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	740
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	741 <list type="bullet">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	742
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	743 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	744 <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	745 <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	746 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	747
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	748 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	749 <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	750 <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	751 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	752
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	753 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	754 <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	755 <literal>"Sep 28 12:00:00"</literal>
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	758 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	759 <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	760 <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	761 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	762
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	763 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	764 <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	765 standard format:
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	766 <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	767 </listitem>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	768
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	769 </list>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	770 </para>
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 <para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	773 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	774 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	775 the cached time value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	776 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	777
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	778 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	779 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	780 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	781 <literal>struct timeval</literal>).
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	782 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	783 calls.
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	784 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	785 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	786 signal handler context.
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	787 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	788
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	789 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	790 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	791 broken-down time representation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	792 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	793 <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	794 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	795
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	796 <list type="bullet">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	797
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	798 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	799 <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	800 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	801
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	802 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	803 <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	804 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	805 </listitem>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	806
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	807 </list>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	808
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	809 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	810 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	811 <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	812 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	813 representation function returns a string representation suitable
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	814 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	815 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	816
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	817 </section>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	818
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	819
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	820 <section name="Containers" id="containers">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	821
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	822
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	823 <section name="Array" id="array">
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	826 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	827 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	828
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	829
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	830 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	831 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	832 void *elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	833 ngx_uint_t nelts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	834 size_t size;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	835 ngx_uint_t nalloc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	836 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	837 } ngx_array_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	838 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	839
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	840 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	841 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	842 The <literal>nelts</literal> field holds the number of elements.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	843 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	844 when the array is initialized.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	845 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	846
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	847 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	848 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	849 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	850 call to initialize an array object that has already been allocated.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	851 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	852
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	853
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	854 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	855 ngx_array_t *a, b;
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 /* create an array of strings with preallocated memory for 10 elements */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	858 a = ngx_array_create(pool, 10, sizeof(ngx_str_t));
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 /* initialize string array for 10 elements */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	861 ngx_array_init(&b, pool, 10, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	862 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	863
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	864 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	865 Use the following functions to add elements to an array:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	866 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	867
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	868 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	869 <list type="bullet">
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 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	872 <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	873 to it
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	876 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	877 <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	878 and returns pointer to the first one
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	881 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	882 </para>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	885 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	886 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	887 are copied to it.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	888 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	889 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	890
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	891
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	892 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	893 s = ngx_array_push(a);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	894 ss = ngx_array_push_n(&b, 3);
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	897 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	898
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 name="List" id="list">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	903 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	904 large number of items.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	905 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	906 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	907
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	908
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	909 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	910 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	911 ngx_list_part_t *last;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	912 ngx_list_part_t part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	913 size_t size;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	914 ngx_uint_t nalloc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	915 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	916 } ngx_list_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	917 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	918
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	919 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	920 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	921 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	922
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	923
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	924 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	925 typedef struct ngx_list_part_s ngx_list_part_t;
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 struct ngx_list_part_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	928 void *elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	929 ngx_uint_t nelts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	930 ngx_list_part_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	931 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	932 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	933
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	934 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	935 Before use, a list must be initialized by calling
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	936 <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	937 <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	938 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	939 items per list part.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	940 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	941 function.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	942 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	943 example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	944 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	945
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	946
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	947 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	948 ngx_str_t *v;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	949 ngx_uint_t i;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	950 ngx_list_t *list;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	951 ngx_list_part_t *part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	952
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	953 list = ngx_list_create(pool, 100, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	954 if (list == NULL) { /* error */ }
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 /* add items to the list */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	957
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	958 v = ngx_list_push(list);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	959 if (v == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	960 ngx_str_set(v, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	961
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	962 v = ngx_list_push(list);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	963 if (v == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	964 ngx_str_set(v, "bar");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	965
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	966 /* iterate over the list */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	967
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	968 part = &list->part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	969 v = part->elts;
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 for (i = 0; /* void */; i++) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	972
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	973 if (i >= part->nelts) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	974 if (part->next == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	975 break;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	976 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	977
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	978 part = part->next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	979 v = part->elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	980 i = 0;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	981 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	982
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	983 ngx_do_smth(&v[i]);
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 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	986
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	987 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	988 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	989 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	990
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	991 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	992 Lists do not support item removal.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	993 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	994 being removed from the list.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	995 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	996 <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	997 <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	998 zero.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	999 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	1000 over.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1001 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1002
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1003 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1004
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 name="Queue" id="queue">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1009 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	1010 follows:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1011 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1012
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1013
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1014 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1015 typedef struct ngx_queue_s ngx_queue_t;
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 struct ngx_queue_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1018 ngx_queue_t *prev;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1019 ngx_queue_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1020 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1021 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1022
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1023 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1024 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	1025 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	1026 before use.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1027 Queues support the following operations:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1028 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1029
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1030 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1031 <list type="bullet">
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 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1034 <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	1035 <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	1036 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1037
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1038 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1039 <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	1040 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1041
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1042 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1043 <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	1044 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	1045 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1046
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1047 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1048 <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	1049 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1050
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1051 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1052 <literal>ngx_queue_head(h)</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1053 <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	1054 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1055
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1056 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1057 <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	1058 iteration at
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1061 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1062 <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	1063 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	1064 it
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1065 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1066
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1067 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1068 </para>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1071 An example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1072 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1073
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1074
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1075 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1076 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1077 ngx_str_t value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1078 ngx_queue_t queue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1079 } ngx_foo_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1080
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1081 ngx_foo_t *f;
2008 1f2f9fa97065 DevGuide: fixed queue example. Vladimir Homutov <vl@nginx.com> parents: 2007 diff changeset	1082 ngx_queue_t values, *q;
1899 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_queue_init(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1085
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1086 f = ngx_palloc(pool, sizeof(ngx_foo_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1087 if (f == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1088 ngx_str_set(&f->value, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1089
2008 1f2f9fa97065 DevGuide: fixed queue example. Vladimir Homutov <vl@nginx.com> parents: 2007 diff changeset	1090 ngx_queue_insert_tail(&values, &f->queue);
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1091
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1092 /* insert more nodes here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1093
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1094 for (q = ngx_queue_head(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1095 q != ngx_queue_sentinel(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1096 q = ngx_queue_next(q))
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1097 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1098 f = ngx_queue_data(q, ngx_foo_t, queue);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1099
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1100 ngx_do_smth(&f->value);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1101 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1102 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1103
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1104 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1105
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 name="Red-Black tree" id="red_black_tree">
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 <para>
1915 8b7c3b0ef1a4 Semantically marked paths. Vladimir Homutov <vl@nginx.com> parents: 1914 diff changeset	1110 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	1111 effective implementation of red-black trees.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1112 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1113
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1114
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1115 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1116 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1117 ngx_rbtree_t rbtree;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1118 ngx_rbtree_node_t sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1119
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1120 /* custom per-tree data here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1121 } my_tree_t;
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 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1124 ngx_rbtree_node_t rbnode;
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 /* custom per-node data */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1127 foo_t val;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1128 } my_node_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1129 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1130
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1131 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1132 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	1133 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	1134 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	1135 your data.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1136 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1137
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1138 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1139 To initialize a tree:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1140 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1141
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1142
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1143 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1144 my_tree_t root;
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 ngx_rbtree_init(&root.rbtree, &root.sentinel, insert_value_function);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1147 </programlisting>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1150 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	1151 "<literal>insert_value</literal>" functions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1152 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	1153 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	1154 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	1155 node to be added, and a tree sentinel.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1156 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1157
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1158
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1159 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1160 void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1161 ngx_rbtree_node_t *node,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1162 ngx_rbtree_node_t *sentinel)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1163 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1164
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1165
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1166 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1167 The traversal is pretty straightforward and can be demonstrated with the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1168 following lookup function pattern:
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1171
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1172 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1173 my_node_t *
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1174 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	1175 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1176 ngx_int_t rc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1177 my_node_t *n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1178 ngx_rbtree_node_t node, sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1179
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1180 node = rbtree->root;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1181 sentinel = rbtree->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 while (node != sentinel) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1184
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1185 n = (my_node_t *) node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1186
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1187 if (hash != node->key) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1188 node = (hash < node->key) ? node->left : node->right;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1189 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1190 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1191
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1192 rc = compare(val, node->val);
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 if (rc < 0) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1195 node = node->left;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1196 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1197 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1198
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1199 if (rc > 0) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1200 node = node->right;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1201 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1202 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1203
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1204 return n;
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 NULL;
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 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1210
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1211 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1212 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	1213 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	1214 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	1215 hash field is used.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1216 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1217
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1218 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1219 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	1220 <literal>ngx_rbtree_insert()</literal>:
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1223
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1224 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1225 my_node_t *my_node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1226 ngx_rbtree_node_t *node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1227
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1228 my_node = ngx_palloc(...);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1229 init_custom_data(&my_node->val);
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 node = &my_node->rbnode;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1232 node->key = create_key(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 ngx_rbtree_insert(&root->rbtree, node);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1235 </programlisting>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1238 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	1239 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1240
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1241
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1242 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1243 ngx_rbtree_delete(&root->rbtree, node);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1244 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1245
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1246 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1247
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1248 <section name="Hash" id="hash">
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1249
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1250 <para>
1920 de5251816480 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1919 diff changeset	1251 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	1252 Both exact and wildcard matching are supported.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1253 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	1254 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1255
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1256 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1257 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	1258 hold so that nginx can build it optimally.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1259 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	1260 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	1261 <link doc="../hash.xml">document</link>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1262 They are usually configurable by the user.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1263 Hash initialization settings are stored with the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1264 <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	1265 <literal>ngx_hash_t</literal>:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1266 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1267 ngx_hash_t foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1268 ngx_hash_init_t hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1269
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1270 hash.hash = &foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1271 hash.key = ngx_hash_key;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1272 hash.max_size = 512;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1273 hash.bucket_size = ngx_align(64, ngx_cacheline_size);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1274 hash.name = "foo_hash";
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1275 hash.pool = cf->pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1276 hash.temp_pool = cf->temp_pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1277 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1278 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	1279 integer key from a string.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1280 There are two generic key-creation functions:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1281 <literal>ngx_hash_key(data, len)</literal> and
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1282 <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	1283 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	1284 must be writeable.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1285 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	1286 to the function, initializing the key array (see below).
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1287 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1288
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1289 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1290 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	1291 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	1292 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	1293 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	1294 <literal>NGX_HASH_LARGE</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1295 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	1296 elements.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1297
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1298 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1299 ngx_hash_keys_arrays_t foo_keys;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1300
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1301 foo_keys.pool = cf->pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1302 foo_keys.temp_pool = cf->temp_pool;
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 ngx_hash_keys_array_init(&foo_keys, NGX_HASH_SMALL);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1305 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1306 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1307
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1308 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1309 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	1310 <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	1311 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1312 ngx_str_t k1 = ngx_string("key1");
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1313 ngx_str_t k2 = ngx_string("key2");
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1314
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1315 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	1316 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	1317 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1318 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1319
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1320 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1321 To build the hash table, call the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1322 <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	1323
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1324 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1325 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	1326 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1327
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1328 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	1329 <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	1330 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1331
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1332 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1333 When the hash is built, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1334 <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	1335 elements:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1336 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1337 my_data_t *data;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1338 ngx_uint_t key;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1339
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1340 key = ngx_hash_key(k1.data, k1.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1341
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1342 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	1343 if (data == NULL) {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1344 /* key not found */
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1345 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1346 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1347
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1348 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1349
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1350 <section name="Wildcard matching" id="wildcard_matching">
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1351
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1352 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1353 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	1354 <literal>ngx_hash_combined_t</literal> type.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1355 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	1356 <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	1357 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	1358 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1359 ngx_hash_init_t hash
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1360 ngx_hash_combined_t foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1361
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1362 hash.hash = &foo_hash.hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1363 hash.key = ...;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1364 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1365 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1366
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1367 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1368 It is possible to add wildcard keys using the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1369 <literal>NGX_HASH_WILDCARD_KEY</literal> flag:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1370 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1371 /* k1 = ".example.org"; */
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1372 /* k2 = "foo."; /
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1373 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	1374 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	1375 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1376 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	1377 Please refer to the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1378 <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	1379 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	1380 matching algorithm.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1381 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1382
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1383 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1384 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	1385 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	1386 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	1387 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1388 if (foo_keys.dns_wc_head.nelts) {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1389
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1390 ngx_qsort(foo_keys.dns_wc_head.elts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1391 (size_t) foo_keys.dns_wc_head.nelts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1392 sizeof(ngx_hash_key_t),
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1393 cmp_dns_wildcards);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1394
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1395 hash.hash = NULL;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1396 hash.temp_pool = pool;
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 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	1399 foo_keys.dns_wc_head.nelts)
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1400 != NGX_OK)
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1401 {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1402 return NGX_ERROR;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1403 }
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 foo_hash.wc_head = (ngx_hash_wildcard_t *) hash.hash;
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 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1408 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	1409 to the combined hash.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1410 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	1411 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1412
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1413 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1414 The lookup in a combined hash is handled by the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1415 <literal>ngx_hash_find_combined(chash, key, name, len)</literal>:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1416 <programlisting>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	1417 /* 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	1418 /* key = "foo.example.com"; — will match "foo." /
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1419
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1420 hkey = ngx_hash_key(key.data, key.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1421 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	1422 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1423 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1424
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1425 </section>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1426
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1427 </section>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1428
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1429 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1430
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 name="Memory management" id="memory_management">
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="Heap" id="heap">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1438 To allocate memory from system heap, use the following functions:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1439 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1440
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1441 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1442 <list type="bullet">
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 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1445 <literal>ngx_alloc(size, log)</literal> — Allocate memory from system heap.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1446 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	1447 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	1448 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1449
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1450 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1451 <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	1452 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	1453 allocation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1454 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1455
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1456 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1457 <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	1458 from system heap.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1459 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	1460 on those platforms that provide that function.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1461 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	1462 provides maximum alignment.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1463 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1464
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1465 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1466 <literal>ngx_free(p)</literal> — Free allocated memory.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1467 This is a wrapper around <literal>free()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1468 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1469
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1470 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1471 </para>
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 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1474
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 name="Pool" id="pool">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1479 Most nginx allocations are done in pools.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1480 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	1481 destroyed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1482 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	1483 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1484
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1485 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1486 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	1487 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	1488 block list.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1489 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	1490 is forwarded to the system allocator and the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1491 returned pointer is stored in the pool for further deallocation.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1492 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1493
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1494 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1495 The type for nginx pools is <literal>ngx_pool_t</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1496 The following operations are supported:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1497 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1498
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1499 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1500 <list type="bullet">
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 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1503 <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	1504 block size.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1505 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	1506 The <literal>size</literal>
f29bd40e9a62 Development guide: documented ngx_create_pool() size requirements. Ruslan Ermilov <ru@nginx.com> parents: 2079 diff changeset	1507 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	1508 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	1509 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1510
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1511 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1512 <literal>ngx_destroy_pool(pool)</literal> — Free all pool memory, including
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1513 the pool object itself.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1514 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1515
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1516 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1517 <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	1518 specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1519 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1520
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1521 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1522 <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	1523 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	1524 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1525
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1526 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1527 <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	1528 specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1529 Mostly used for allocating strings.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1530 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1531
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1532 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1533 <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	1534 allocated in the specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1535 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	1536 can be freed.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1537 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1538
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1539 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1540 </para>
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 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1543 u_char *p;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1544 ngx_str_t *s;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1545 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1546
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1547 pool = ngx_create_pool(1024, log);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1548 if (pool == NULL) { /* error */ }
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 s = ngx_palloc(pool, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1551 if (s == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1552 ngx_str_set(s, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1553
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1554 p = ngx_pnalloc(pool, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1555 if (p == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1556 ngx_memcpy(p, "foo", 3);
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1557 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1558
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1559 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1560 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	1561 so the nginx pool implementation provides a way to reuse them.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1562 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	1563 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	1564 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	1565 <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	1566 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	1567 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	1568 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	1569 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1570
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1571 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1572 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	1573 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	1574 destroyed.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1575 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	1576 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	1577 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	1578 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	1579 the main object.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1580 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1581
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1582 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1583 To register a pool cleanup, call
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1584 <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	1585 <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	1586 be filled in by the caller.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1587 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	1588 handler.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1589 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1590
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1591
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1592 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1593 ngx_pool_cleanup_t *cln;
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 cln = ngx_pool_cleanup_add(pool, 0);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1596 if (cln == NULL) { /* error */ }
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->handler = ngx_my_cleanup;
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1599 cln->data = "foo";
1899 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 ...
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1602
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1603 static void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1604 ngx_my_cleanup(void *data)
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 u_char *msg = data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1607
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1608 ngx_do_smth(msg);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1609 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1610 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1611
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1612 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1613
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 name="Shared memory" id="shared_memory">
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1618 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	1619 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	1620 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	1621 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	1622 of the zone.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1623 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	1624 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	1625 <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	1626 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	1627 different tag.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1628 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	1629 <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	1630 one nginx module.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1631 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1632
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1633 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1634 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	1635 following fields:
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1638 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1639 <list type="bullet">
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 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1642 <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	1643 is mapped to actual memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1644 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1645
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1646 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1647 <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	1648 <literal>init</literal> callback
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1649 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1650
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1651 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1652 <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	1653 old cycle
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1654 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1655
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1656 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1657 <literal>tag</literal> — Shared zone tag
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1658 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1659
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1660 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1661 <literal>shm</literal> — Platform-specific object of type
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1662 <literal>ngx_shm_t</literal>, having at least the following fields:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1663 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1664
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1665 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1666 <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	1667 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1668
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1669 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1670 <literal>size</literal> — Shared memory size
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1671 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1672
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1673 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1674 <literal>name</literal> — Shared memory name
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1675 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1676
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1677 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1678 <literal>log</literal> — Shared memory log
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1679 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1680
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1681 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1682 <literal>exists</literal> — Flag that indicates shared memory was inherited
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1683 from the master process (Windows-specific)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1684 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1685
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1686 </list>
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 </para>
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1693 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	1694 <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	1695 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	1696 shared anonymous mapping.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1697 On Windows, the <literal>CreateFileMapping()</literal>/
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1698 <literal>MapViewOfFileEx()</literal> pair is used.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1699 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1700
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1701 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1702 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	1703 <literal>ngx_slab_pool_t</literal> type.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1704 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	1705 zone.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1706 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	1707 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	1708 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	1709 <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	1710 <literal>ngx_slab_calloc(pool, size)</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1711 To free memory, call <literal>ngx_slab_free(pool, p)</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1712 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1713
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1714 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1715 Slab pool divides all shared zone into pages.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1716 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	1717 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	1718 8 bytes.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1719 Nonconforming values are rounded up.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1720 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	1721 allocation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1722 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	1723 done an entire page at a time
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1724 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1725
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1726 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1727 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	1728 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	1729 <literal>ngx_slab_pool_t</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1730 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	1731 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	1732 in the shared zone.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1733 To lock or unlock a mutex, call
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1734 <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	1735 <literal>ngx_shmtx_unlock(&shpool->mutex)</literal> respectively.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1736 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1737
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1738
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1739 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1740 ngx_str_t name;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1741 ngx_foo_ctx_t *ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1742 ngx_shm_zone_t *shm_zone;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1743
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1744 ngx_str_set(&name, "foo");
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1745
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1746 /* allocate shared zone context */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1747 ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1748 if (ctx == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1749 /* error */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1750 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1751
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1752 /* add an entry for 64k shared zone */
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1753 shm_zone = ngx_shared_memory_add(cf, &name, 65536, &ngx_foo_module);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1754 if (shm_zone == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1755 /* error */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1756 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1757
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1758 /* register init callback and context */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1759 shm_zone->init = ngx_foo_init_zone;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1760 shm_zone->data = ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1761
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1762
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1763 ...
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 static ngx_int_t
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1767 ngx_foo_init_zone(ngx_shm_zone_t shm_zone, void data)
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 ngx_foo_ctx_t *octx = data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1770
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1771 size_t len;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1772 ngx_foo_ctx_t *ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1773 ngx_slab_pool_t *shpool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1774
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1775 value = shm_zone->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1776
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1777 if (octx) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1778 /* reusing a shared zone from old cycle */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1779 ctx->value = octx->value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1780 return NGX_OK;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1781 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1782
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1783 shpool = (ngx_slab_pool_t *) shm_zone->shm.addr;
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 if (shm_zone->shm.exists) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1786 /* initialize shared zone context in Windows nginx worker */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1787 ctx->value = shpool->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1788 return NGX_OK;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1789 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1790
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1791 /* initialize shared zone */
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 ctx->value = ngx_slab_alloc(shpool, sizeof(ngx_uint_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1794 if (ctx->value == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1795 return NGX_ERROR;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1796 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1797
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1798 shpool->data = ctx->value;
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 return NGX_OK;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1801 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1802 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1803
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1804 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1805
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 name="Logging" id="logging">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1813 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	1814 The nginx logger supports several types of output:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1815
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1816 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1817
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1818 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1819 stderr — Logging to standard error (stderr)
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1820 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1821
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1822 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1823 file — Logging to a file
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1824 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1825
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1826 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1827 syslog — Logging to syslog
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1828 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1829
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1830 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1831 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	1832 can be accessed later with a debugger
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1833 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1834
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1835 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1836 </para>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1839 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	1840 the <literal>next</literal> field.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1841 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	1842 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1843
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1844 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1845 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	1846 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	1847 The following severity levels are supported:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1848 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1849
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1850 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1851 <list type="bullet">
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 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1854 <literal>NGX_LOG_EMERG</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1855 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1856
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1857 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1858 <literal>NGX_LOG_ALERT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1859 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1860
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1861 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1862 <literal>NGX_LOG_CRIT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1863 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1864
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1865 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1866 <literal>NGX_LOG_ERR</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1867 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1868
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1869 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1870 <literal>NGX_LOG_WARN</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1871 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1872
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1873 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1874 <literal>NGX_LOG_NOTICE</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1875 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1876
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1877 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1878 <literal>NGX_LOG_INFO</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1879 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1880
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1881 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1882 <literal>NGX_LOG_DEBUG</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1883 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1884
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1885 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1886 </para>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1889 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	1890 The debug masks are:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1891 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1892
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1893 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1894 <list type="bullet">
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 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1897 <literal>NGX_LOG_DEBUG_CORE</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1898 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1899
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1900 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1901 <literal>NGX_LOG_DEBUG_ALLOC</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1902 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1903
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1904 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1905 <literal>NGX_LOG_DEBUG_MUTEX</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1906 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1907
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1908 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1909 <literal>NGX_LOG_DEBUG_EVENT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1910 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1911
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1912 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1913 <literal>NGX_LOG_DEBUG_HTTP</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1914 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1915
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1916 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1917 <literal>NGX_LOG_DEBUG_MAIL</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1918 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1919
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1920 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1921 <literal>NGX_LOG_DEBUG_STREAM</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1922 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1923
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1924 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1925 </para>
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1928 Normally, loggers are created by existing nginx code from
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1929 <literal>error_log</literal> directives and are available at nearly every stage
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1930 of processing in cycle, configuration, client connection and other objects.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1931 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1932
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1933 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1934 Nginx provides the following logging macros:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1935 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1936
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1937 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1938 <list type="bullet">
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 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1941 <literal>ngx_log_error(level, log, err, fmt, ...)</literal> — Error logging
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1942 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1943
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1944 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1945 <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	1946 <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	1947 logging with up to eight supported formatting arguments
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1948 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1949
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1950 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1951 </para>
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1954 A log message is formatted in a buffer of size
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1955 <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	1956 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	1957 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	1958 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	1959 prepend more specific information to the log message.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1960 HTTP module sets <literal>ngx_http_log_error()</literal> function as log
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1961 handler to log client and server addresses, current action (stored in
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1962 <literal>log->action</literal>), client request line, server name etc.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1963 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1964
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1965 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1966 /* specify what is currently done */
2258 2c8c10f00518 Development guide: fixed quotes encoding in <programlisting>. Sergey Kandaurov <pluknet@nginx.com> parents: 2170 diff changeset	1967 log->action = "sending mp4 to client";
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1968
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1969 /* error and debug log */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1970 ngx_log_error(NGX_LOG_INFO, c->log, 0, "client prematurely
2258 2c8c10f00518 Development guide: fixed quotes encoding in <programlisting>. Sergey Kandaurov <pluknet@nginx.com> parents: 2170 diff changeset	1971 closed connection");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1972
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1973 ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0,
2258 2c8c10f00518 Development guide: fixed quotes encoding in <programlisting>. Sergey Kandaurov <pluknet@nginx.com> parents: 2170 diff changeset	1974 "mp4 start:%ui, length:%ui", mp4->start, mp4->length);
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1975 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1976
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1977 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1978 The example above results in log entries like these:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1979 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1980
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1981
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1982 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1983 2016/09/16 22:08:52 [info] 17445#0: *1 client prematurely closed connection while
2258 2c8c10f00518 Development guide: fixed quotes encoding in <programlisting>. Sergey Kandaurov <pluknet@nginx.com> parents: 2170 diff changeset	1984 sending mp4 to client, client: 127.0.0.1, server: , request: "GET /file.mp4 HTTP/1.1"
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1985 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	1986 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1987
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1988 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1989
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 name="Cycle" id="cycle">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1994 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	1995 configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1996 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	1997 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	1998 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	1999 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	2000 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	2001 successfully created.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2002 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2003
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2004 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2005 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	2006 takes the previous cycle as its argument.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2007 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	2008 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	2009 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	2010 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	2011 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2012
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2013 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2014 Members of the cycle include:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2015 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2016
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2017 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2018 <list type="bullet">
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 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2021 <literal>pool</literal> — Cycle pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2022 Created for each new cycle.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2023 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2024
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2025 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2026 <literal>log</literal> — Cycle log.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2027 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	2028 <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	2029 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2030
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2031 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2032 <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	2033 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	2034 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2035
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2036 <listitem>
1981 082724c57c38 Fixes in cycle section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1980 diff changeset	2037 <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	2038 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	2039 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	2040 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	2041 sets the number of connections <literal>connection_n</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2042 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2043
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2044 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2045 <literal>free_connections</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2046 <literal>free_connection_n</literal> — List and number of currently available
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2047 connections.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2048 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	2049 or connect to upstream servers.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2050 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2051
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2052 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2053 <literal>files</literal>, <literal>files_n</literal> — Array for mapping file
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2054 descriptors to nginx connections.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2055 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	2056 <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	2057 <literal>poll</literal> and <literal>devpoll</literal>).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2058 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2059
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2060 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2061 <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	2062 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	2063 files.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2064 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2065
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2066 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2067 <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	2068 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	2069 the current configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2070 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2071
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2072 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2073 <literal>listening</literal> — Array of listening objects of type
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2074 <literal>ngx_listening_t</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2075 Listening objects are normally added by the <literal>listen</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2076 directive of different modules which call the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2077 <literal>ngx_create_listening()</literal> function.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2078 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	2079 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2080
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2081 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2082 <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	2083 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	2084 modules which are going to operate on certain directories.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2085 These directories are created by nginx after reading configuration, if missing.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2086 Moreover, two handlers can be added for each path:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2087
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2088 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2089
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2090 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2091 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	2092 nginx.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2093 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	2094 memory.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2095 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	2096 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2097
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2098 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2099 path manager — Executes periodically.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2100 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	2101 memory to reflect the changes.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2102 The handler is called from the dedicated “nginx cache manager” process.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2103 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2104
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2105 </list>
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 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2109 <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	2110 <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	2111 <literal>ngx_conf_open_file()</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2112 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	2113 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	2114 <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	2115 object's <literal>fd</literal> field.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2116 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	2117 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	2118 reopen signal (most often <literal>USR1</literal>).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2119 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	2120 new value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2121 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2122
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2123 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2124 <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	2125 calling the <literal>ngx_shared_memory_add()</literal> function.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2126 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	2127 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	2128 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2129
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2130 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2131 </para>
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 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2134
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2135 <section name="Buffer" id="buffer">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2136
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2137 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2138 For input/output operations, nginx provides the buffer type
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2139 <literal>ngx_buf_t</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2140 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	2141 source.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2142 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	2143 possible for a buffer to reference both at the same time.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2144 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	2145 structure <literal>ngx_buf_t</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2146 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2147
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2148 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2149 The <literal>ngx_buf_t</literal> structure has the following fields:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2150 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2151
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2152 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2153 <list type="bullet">
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 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2156 <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	2157 block allocated for the buffer.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2158 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2159
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2160 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2161 <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	2162 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	2163 <literal>end</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2164 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2165
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2166 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2167 <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	2168 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	2169 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2170
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2171 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2172 <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	2173 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	2174 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2175
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2176 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2177 <literal>file</literal> — File object.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2178 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2179
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2180 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2181 <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	2182 writable memory.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2185 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2186 <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	2187 memory.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2190 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2191 <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	2192 in a file.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2195 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2196 <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	2197 need to be flushed.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2200 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2201 <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	2202 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	2203 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2204
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2205 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2206 <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	2207 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	2208 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	2209 nginx to skip the error check.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2210 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2211
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2212 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2213 <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	2214 output.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2217 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2218 <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	2219 buffers in a request or subrequest.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2222 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2223 <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	2224 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	2225 shadow.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2226 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	2227 consumed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2228 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2229
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2230 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2231 <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	2232 one that references a particular shadow buffer.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2235 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2236 <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	2237 file.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2238 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2239
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2240 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2241 </para>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2244 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	2245 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	2246 defined as follows:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2247 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2248
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2249
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2250 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2251 typedef struct ngx_chain_s ngx_chain_t;
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 struct ngx_chain_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2254 ngx_buf_t *buf;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2255 ngx_chain_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2256 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2257 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2258
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2259 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2260 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	2261 chain link.
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2264 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2265 An example of using buffers and chains:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2266 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2267
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2268
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2269 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2270 ngx_chain_t *
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2271 ngx_get_my_chain(ngx_pool_t *pool)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2272 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2273 ngx_buf_t *b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2274 ngx_chain_t out, cl, **ll;
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 /* first buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2277 cl = ngx_alloc_chain_link(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2278 if (cl == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2279
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2280 b = ngx_calloc_buf(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2281 if (b == 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->start = (u_char *) "foo";
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2284 b->pos = b->start;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2285 b->end = b->start + 3;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2286 b->last = b->end;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2287 b->memory = 1; /* read-only memory */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2288
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2289 cl->buf = b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2290 out = cl;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2291 ll = &cl->next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2292
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2293 /* second buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2294 cl = ngx_alloc_chain_link(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2295 if (cl == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2296
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2297 b = ngx_create_temp_buf(pool, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2298 if (b == 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->last = ngx_cpymem(b->last, "foo", 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2301
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2302 cl->buf = b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2303 cl->next = NULL;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2304 *ll = cl;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2305
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2306 return out;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2307 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2308 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2309
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2310 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2311
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 name="Networking" id="networking">
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 <!--
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2317 <section name="Network data types" id="network_data_types">
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2320 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	2321 address...
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2324 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2325 -->
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 name="Connection" id="connection">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2330 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	2331 socket descriptor.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2332 It includes the following fields:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2333 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2334
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2335 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2336 <list type="bullet">
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 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2339 <literal>fd</literal> — Socket descriptor
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2340 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2341
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2342 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2343 <literal>data</literal> — Arbitrary connection context.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2344 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	2345 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	2346 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2347
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2348 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2349 <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	2350 the connection.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2351 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2352
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2353 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2354 <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	2355 <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	2356 for the connection.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2357 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2358
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2359 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2360 <literal>pool</literal> — Connection pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2361 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2362
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2363 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2364 <literal>log</literal> — Connection log.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2365 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2366
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2367 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2368 <literal>sockaddr</literal>, <literal>socklen</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2369 <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	2370 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2371
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2372 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2373 <literal>local_sockaddr</literal>, <literal>local_socklen</literal> — Local
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2374 socket address in binary form.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2375 Initially, these fields are empty.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2376 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	2377 local socket address.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2378 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2379
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2380 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2381 <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	2382 - 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	2383 the connection.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2384 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2385
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2386 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2387 <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	2388 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2389
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2390 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2391 <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	2392 makes it eligible for reuse.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2395 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2396 <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	2397 and needs to be closed.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2398 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2399
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2400 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2401 </para>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2404 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	2405 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	2406 <literal>ngx_ssl_connection_t</literal> structure, keeping all SSL-related data
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2407 for the connection, including <literal>SSL_CTX</literal> and
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2408 <literal>SSL</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2409 The <literal>recv</literal>, <literal>send</literal>,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2410 <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	2411 set to SSL-enabled functions as well.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2412 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2413
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2414 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2415 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	2416 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	2417 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	2418 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	2419 To retrieve a connection structure, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2420 <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	2421 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	2422 to be wrapped in a connection structure.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2423 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2424
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2425 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2426 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	2427 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	2428 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	2429 <literal>ngx_reusable_connection(c, reusable)</literal> function.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2430 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	2431 <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	2432 connection into the <literal>reusable_connections_queue</literal> of the cycle.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2433 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	2434 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	2435 it calls <literal>ngx_drain_connections()</literal> to release a
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2436 specific number of reusable connections.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2437 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	2438 handler is called which is supposed to free the connection by calling
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2439 <literal>ngx_close_connection(c)</literal> and make it available for reuse.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2440 To exit the state when a connection can be reused
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2441 <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	2442 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	2443 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	2444 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2445
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2446 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2447
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 name="Events" id="events">
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="Event" id="event">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2458 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	2459 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	2460 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2461
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2462 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2463 Fields in <literal>ngx_event_t</literal> include:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2464 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2465
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2466 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2467 <list type="bullet">
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 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2470 <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	2471 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	2472 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2473
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2474 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2475 <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	2476 happens.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2479 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2480 <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	2481 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	2482 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2483
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2484 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2485 <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	2486 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	2487 <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	2488 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2489
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2490 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2491 <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	2492 I/O notification.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2495 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2496 <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	2497 limiting.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2500 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2501 <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	2502 the timer tree.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2505 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2506 <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	2507 not yet expired.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2510 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2511 <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	2512 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2513
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2514 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2515 <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	2516 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2517
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2518 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2519 <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	2520 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	2521 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	2522 <literal>epoll</literal> event or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2523 <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	2524 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2525
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2526 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2527 <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	2528 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	2529 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2530
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2531 <listitem>
1995 80f53da7280c Updated cancelable event description in the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1994 diff changeset	2532 <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	2533 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	2534 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	2535 events scheduled.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2536 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2537
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2538 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2539 <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	2540 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2541
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2542 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2543 <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	2544 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2545
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2546 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2547 </para>
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 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2550
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 name="I/O events" id="i_o_events">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2555 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	2556 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	2557 <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	2558 socket is ready for reading or writing.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2559 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	2560 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	2561 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	2562 repeated read notification until more data arrives on the socket.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2563 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	2564 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	2565 converts the notifications to Edge-Triggered.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2566 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	2567 on different platforms, the functions
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2568 <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	2569 <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	2570 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	2571 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	2572 event handler.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2573 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2574
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2575 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2576
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 name="Timer events" id="timer_events">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2581 An event can be set to send a notification when a timeout expires.
2170 2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2582 The timer used by events counts milliseconds since some unspecified point
2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2583 in the past truncated to <literal>ngx_msec_t</literal> type.
2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2584 Its current value can be obtained from the <literal>ngx_current_msec</literal>
2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2585 variable.
2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2586 </para>
2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2587
2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2588 <para>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2589 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	2590 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	2591 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	2592 stores all timeouts currently set.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2593 The key in the tree is of type <literal>ngx_msec_t</literal> and is the time
2170 2bc348966475 Development guide: updated Time and Events chapters. Vladimir Homutov <vl@nginx.com> parents: 2153 diff changeset	2594 when the event occurs.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2595 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	2596 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	2597 for I/O events and for expiring timeout events.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2598 </para>
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>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2603 <section name="Posted events" id="posted_events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2604
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2605 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2606 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	2607 point later within the current event loop iteration.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2608 Posting events is a good practice for simplifying code and escaping stack
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2609 overflows.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2610 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	2611 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	2612 <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	2613 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	2614 <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	2615 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	2616 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	2617 events are already handled.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2618 The function <literal>ngx_event_process_posted()</literal> is called to process
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2619 an event queue.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2620 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	2621 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	2622 within the current event loop iteration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2623 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2624
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2625 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2626 An example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2627 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2628
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2629
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2630 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2631 void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2632 ngx_my_connection_read(ngx_connection_t *c)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2633 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2634 ngx_event_t *rev;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2635
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2636 rev = c->read;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2637
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2638 ngx_add_timer(rev, 1000);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2639
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2640 rev->handler = ngx_my_read_handler;
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 ngx_my_read(rev);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2643 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2644
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 void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2647 ngx_my_read_handler(ngx_event_t *rev)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2648 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2649 ssize_t n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2650 ngx_connection_t *c;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2651 u_char buf[256];
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2652
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2653 if (rev->timedout) { /* timeout expired */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2654
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2655 c = rev->data;
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 while (rev->ready) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2658 n = c->recv(c, buf, sizeof(buf));
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 if (n == NGX_AGAIN) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2661 break;
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2664 if (n == NGX_ERROR) { /* error */ }
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 /* process buf */
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2669 if (ngx_handle_read_event(rev, 0) != NGX_OK) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2670 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2671 </programlisting>
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>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2676 <section name="Event loop" id="event_loop">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2677
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2678 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2679 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	2680 event loop.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2681 (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	2682 <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	2683 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	2684 <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	2685 repeatedly until the process exits.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2686 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2687
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2688 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2689 The event loop has the following stages:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2690
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2691 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2692
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2693 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2694 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	2695 <literal>ngx_event_find_timer()</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2696 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	2697 number of milliseconds until the node expires.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2698 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2699
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2700 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2701 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	2702 mechanism, chosen by nginx configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2703 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	2704 timeout expires.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2705 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	2706 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	2707 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	2708 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	2709 events.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2710 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2711
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2712 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2713 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	2714 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	2715 unexpired timeout is found.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2716 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	2717 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	2718 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2719
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2720 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2721 Process posted events by calling <literal>ngx_event_process_posted()</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2722 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	2723 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	2724 </listitem>
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 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2727 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2728
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2729 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2730 All nginx processes handle signals as well.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2731 Signal handlers only set global variables which are checked after the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2732 <literal>ngx_process_events_and_timers()</literal> call.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2733 </para>
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>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2741 <section name="Processes" id="processes">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2742
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2743 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2744 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	2745 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	2746 global variable, and is one of the following:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2747 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2748
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2749 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2750
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2751 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2752
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2753 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2754 <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	2755 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	2756 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	2757 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	2758 </para>
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
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2761 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2762
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2763 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2764
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2765 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2766 <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	2767 connections.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2768 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	2769 commands as well.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2770 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	2771 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	2772 <literal>worker_processes</literal> directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2773 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2774
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2775 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2776
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2777 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2778
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2779 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2780 <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	2781 <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	2782 that mode.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2783 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	2784 (like the worker process does).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2785 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	2786 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2787
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2788 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2789
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2790 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2791
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2792 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2793 <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	2794 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	2795 The cycle function for both is
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2796 <literal>ngx_cache_manager_process_cycle()</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2797 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2798
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2799 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2800
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2801 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2802
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2803 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2804 The nginx processes handle the following signals:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2805 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2806
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2807 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2808
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2809 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2810
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2811 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2812 <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	2813 systems) — Gracefully shutdown.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2814 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	2815 child processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2816 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	2817 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	2818 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	2819 cycle pool and exits.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2820 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	2821 exits immediately.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2822 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	2823 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	2824 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	2825 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	2826 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2827
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2828 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2829
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2830 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2831
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2832 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2833 <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	2834 systems) — Terminate.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2835 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	2836 child processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2837 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	2838 <literal>SIGKILL</literal> signal to kill it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2839 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	2840 exits.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2841 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	2842 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	2843 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	2844 when this signal is received.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2845 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2846
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2847 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2848
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2849 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2850
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2851 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2852 <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	2853 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	2854 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	2855 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	2856 master are started again.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2857 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	2858 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	2859 </para>
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
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2862 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2863
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2864 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2865
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2866 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2867 <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	2868 systems) - Reconfigure.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2869 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	2870 creates a new cycle based on it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2871 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	2872 child processes are started.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2873 Meanwhile, the old child processes receive the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2874 <literal>NGX_SHUTDOWN_SIGNAL</literal> signal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2875 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	2876 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	2877 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	2878 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2879
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2880 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2881
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2882 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2883
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2884 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2885 <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	2886 systems) — Reopen files.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2887 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	2888 <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	2889 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2890
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2891 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2892
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2893 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2894
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2895 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2896 <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	2897 systems) — Change the nginx binary.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2898 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	2899 sockets.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2900 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	2901 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	2902 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	2903 sockets to its init cycle.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2904 Other processes ignore this signal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2905 </para>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2906
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2907 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2908
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2909 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2910
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2911 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2912 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	2913 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	2914 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	2915 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	2916 between all nginx processes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2917 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	2918 The messages carry the standard signals.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2919 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2920
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2921 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2922
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2923 <section name="Threads" id="threads">
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2924
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2925 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2926 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	2927 block the nginx worker process.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2928 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	2929 <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	2930 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	2931 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	2932 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	2933 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	2934 intended as a replacement.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2935 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2936
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2937 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2938 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	2939 <literal>pthreads</literal> primitives are available:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2940
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2941 <list type="bullet">
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 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2944 <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	2945
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2946 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2947
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 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2950 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	2951 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2952
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 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2955 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	2956 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2957
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 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2960 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	2961 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2962
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 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2965 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	2966 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2967
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2968 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2969
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2970 </listitem>
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 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2973 <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	2974
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2975 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2976
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 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2979 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	2980 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2981
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 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2984 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	2985 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2986
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 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2989 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	2990 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2991
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2992 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2993 <literal>ngx_int_t
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2994 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	2995 ngx_log_t *log);</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2996 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2997
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2998 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	2999
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3000 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3001
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3002 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3003
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3004 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3005
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3006 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3007 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	3008 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	3009 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	3010 (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	3011 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	3012 that process a queue of tasks.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3013 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	3014 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3015
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3016 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3017 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	3018 relevant definitions:
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3019 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3020 struct ngx_thread_task_s {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3021 ngx_thread_task_t *next;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3022 ngx_uint_t id;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3023 void *ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3024 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	3025 ngx_event_t event;
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
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3028 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	3029
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3030 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	3031 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	3032
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3033 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	3034 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	3035
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3036 </programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3037 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	3038 reference to a thread pool by calling
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3039 <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	3040 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	3041 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	3042 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3043
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3044 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3045 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	3046 <literal>tp</literal> at runtime, use the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3047 <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	3048
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3049 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	3050 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	3051 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3052 typedef struct {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3053 int foo;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3054 } my_thread_ctx_t;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3055
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 static void
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3058 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	3059 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3060 my_thread_ctx_t *ctx = data;
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 /* 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	3063 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3064
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 static void
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3067 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	3068 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3069 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	3070
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3071 /* executed in nginx event loop */
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3072 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3073
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 ngx_int_t
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3076 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	3077 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3078 my_thread_ctx_t *ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3079 ngx_thread_task_t *task;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3080
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3081 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	3082 if (task == NULL) {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3083 return NGX_ERROR;
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
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3086 ctx = task->ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3087
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3088 ctx->foo = 42;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3089
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3090 task->handler = my_thread_func;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3091 task->event.handler = my_thread_completion;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3092 task->event.data = ctx;
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 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	3095 return NGX_ERROR;
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
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3098 return NGX_OK;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3099 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3100 </programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3101
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3102 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3103
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3104 </section>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3105
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3106
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3107 <section name="Modules" id="Modules">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3108
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3109 <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	3110 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3111 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	3112 at least two files:
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3113 <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	3114 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	3115 integrate the module, for example:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3116 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3117 ngx_module_type=CORE
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3118 ngx_module_name=ngx_foo_module
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3119 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	3120
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3121 . auto/module
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3122
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3123 ngx_addon_name=$ngx_module_name
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3124 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3125 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	3126 and access the following variables:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3127 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3128
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3129 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3130 <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	3131 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	3132 <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	3133 <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	3134 <literal>STREAM</literal>, or <literal>MISC</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3135 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3136
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3137 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3138 <literal>ngx_module_name</literal> — Module names.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3139 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	3140 whitespace-separated list of names.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3141 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	3142 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	3143 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3144
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 <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	3147 on the console from the configure script.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3148 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3149
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3150 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3151 <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	3152 files used to compile the module.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3153 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	3154 to the module directory.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3155 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3156
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3157 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3158 <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	3159 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3160
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3161 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3162 <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	3163 dependencies.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3164 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	3165 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3166
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3167 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3168 <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	3169 link with the module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3170 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	3171 <literal>libpthread</literal> library.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3172 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	3173 nginx:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3174 <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	3175 <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	3176 <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	3177 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3178
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3179 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3180 <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	3181 <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	3182 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	3183 depending on linking type.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3184 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3185
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3186 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3187 <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	3188 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	3189 <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	3190 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	3191 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	3192 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	3193 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	3194
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3195 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3196 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	3197 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	3198 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	3199 the first to be executed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3200 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	3201 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	3202 executed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3203 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3204
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3205 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3206 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	3207 <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	3208 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	3209 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	3210 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3211
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3212 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3213
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3214 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3215
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3216 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	3217 <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	3218 script.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3219 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	3220 <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	3221 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3222
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3223 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3224
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3225
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3226 <section name="Core Modules" id="core_modules">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3227
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3228 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3229 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	3230 implemented as modules.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3231 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	3232 <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	3233 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3234 struct ngx_module_s {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3235
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3236 /* private part is omitted */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3237
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3238 void *ctx;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3239 ngx_command_t *commands;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3240 ngx_uint_t type;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3241
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3242 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	3243
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3244 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	3245
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3246 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	3247 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	3248 void (exit_thread)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3249 void (exit_process)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3250
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3251 void (exit_master)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3252
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3253 /* stubs for future extensions are omitted */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3254 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3255 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3256 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	3257 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	3258 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3259
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3260 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3261 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	3262 recognizes the configuration directives, specified in the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3263 <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	3264 nginx lifecycle.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3265 The module lifecycle consists of the following events:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3266
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3267 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3268
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3269 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3270 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	3271 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	3272 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3273
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3274 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3275 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	3276 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	3277 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	3278 time a configuration is loaded.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3279 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3280
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 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	3283 <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	3284 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3285
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3286 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3287 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	3288 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	3289 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3290
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 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	3293 exiting.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3294 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3295
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3296 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3297
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3298 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	3299 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	3300 handlers are not currently called.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3301 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	3302 unnecessary overhead.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3303 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3304
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3305 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3306 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	3307 <literal>ctx</literal> field.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3308 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	3309 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3310 <listitem><literal>NGX_CORE_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3311 <listitem><literal>NGX_EVENT_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3312 <listitem><literal>NGX_HTTP_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3313 <listitem><literal>NGX_MAIL_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3314 <listitem><literal>NGX_STREAM_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3315 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3316 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	3317 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	3318 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	3319 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	3320 requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3321 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3322
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3323 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3324 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	3325 <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	3326 <literal>ngx_thread_pool_module</literal> and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3327 <literal>ngx_openssl_module</literal> modules.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3328 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	3329 modules too.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3330 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	3331 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3332 typedef struct {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3333 ngx_str_t name;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3334 void (create_conf)(ngx_cycle_t *cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3335 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	3336 } ngx_core_module_t;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3337 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3338 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	3339 <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	3340 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	3341 respectively.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3342 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	3343 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	3344 is parsed successfully.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3345 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	3346 configuration and sets default values.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3347 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3348
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3349 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3350 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	3351 look like this:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3352 <programlisting>
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 * Copyright (C) Author.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3355 */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3356
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 #include <ngx_config.h>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3359 #include <ngx_core.h>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3360
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3361
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3362 typedef struct {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3363 ngx_flag_t enable;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3364 } ngx_foo_conf_t;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3365
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 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	3368 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	3369
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3370 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	3371 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	3372
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3373
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3374 static ngx_command_t ngx_foo_commands[] = {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3375
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3376 { ngx_string("foo_enabled"),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3377 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	3378 ngx_conf_set_flag_slot,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3379 0,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3380 offsetof(ngx_foo_conf_t, enable),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3381 &ngx_foo_enable_post },
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 ngx_null_command
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3384 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3385
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3386
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3387 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	3388 ngx_string("foo"),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3389 ngx_foo_create_conf,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3390 ngx_foo_init_conf
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3391 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3392
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3393
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3394 ngx_module_t ngx_foo_module = {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3395 NGX_MODULE_V1,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3396 &ngx_foo_module_ctx, /* module context */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3397 ngx_foo_commands, /* module directives */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3398 NGX_CORE_MODULE, /* module type */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3399 NULL, /* init master */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3400 NULL, /* init module */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3401 NULL, /* init process */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3402 NULL, /* init thread */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3403 NULL, /* exit thread */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3404 NULL, /* exit process */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3405 NULL, /* exit master */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3406 NGX_MODULE_V1_PADDING
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3407 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3408
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 static void *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3411 ngx_foo_create_conf(ngx_cycle_t *cycle)
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3412 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3413 ngx_foo_conf_t *fcf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3414
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3415 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	3416 if (fcf == NULL) {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3417 return NULL;
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
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3420 fcf->enable = NGX_CONF_UNSET;
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 return fcf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3423 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3424
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 static char *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3427 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	3428 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3429 ngx_foo_conf_t *fcf = conf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3430
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3431 ngx_conf_init_value(fcf->enable, 0);
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 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3434 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3435
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 static char *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3438 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	3439 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3440 ngx_flag_t *fp = data;
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 if (*fp == 0) {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3443 return NGX_CONF_OK;
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
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3446 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	3447
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3448 return NGX_CONF_OK;
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 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3451 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3452
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3453 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3454
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3455
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3456 <section name="Configuration Directives" id="config_directives">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3457
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3458 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3459 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	3460 directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3461 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	3462 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	3463 <programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3464 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	3465
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3466 struct ngx_command_s {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3467 ngx_str_t name;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3468 ngx_uint_t type;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3469 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	3470 ngx_uint_t conf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3471 ngx_uint_t offset;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3472 void *post;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3473 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3474 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3475 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	3476 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	3477 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	3478 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	3479 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	3480 The flags are:
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3481
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3482 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3483
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3484 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3485 <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	3486 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3487
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3488 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3489 <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	3490 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3491
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3492 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3493 <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	3494 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3495
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 <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	3498 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	3499 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3500
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3501 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3502 <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	3503 <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	3504 <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	3505 arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3506 Options are limited to the given numbers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3507 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	3508 arguments.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3509 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3510
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3511 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3512
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3513 The flags for directive types are:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3514
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3515 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3516
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3517 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3518 <literal>NGX_CONF_BLOCK</literal> — Directive is a block, that is, it can
2153 ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	3519 contain other directives within its opening and closing braces, or even
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3520 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	3521 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3522
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3523 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3524 <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	3525 <literal>on</literal> or <literal>off</literal>.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3526 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3527
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3528 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3529
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3530 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	3531
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3532 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3533
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3534 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3535 <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	3536 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3537
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3538 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3539 <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	3540 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3541
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 <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	3544 within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3545 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3546
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 <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	3549 within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3550 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3551
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 <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	3554 within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3555 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3556
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 <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	3559 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	3560 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3561
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 <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	3564 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	3565 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3566
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 <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	3569 block within the <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3570 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3571
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 <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	3574 block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3575 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3576
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 <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	3579 within the <literal>stream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3580 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3581
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 <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	3584 within the <literal>stream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3585 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3586
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3587 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3588 <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	3589 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3590
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 <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	3593 within the <literal>mail</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3594 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3595
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3596 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3597 <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	3598 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3599
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3600 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3601 <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	3602 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	3603 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	3604 argument.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3605 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3606 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3607
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3608 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	3609 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	3610 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	3611 store their values in distinct places.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3612 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3613
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3614 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3615 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	3616 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	3617 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	3618
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3619 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3620
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3621 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3622 <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	3623 <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	3624 <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	3625 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3626
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 <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	3629 <literal>ngx_str_t</literal> type.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3630 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3631
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3632 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3633 <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	3634 <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	3635 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	3636 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3637
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3638 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3639 <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	3640 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	3641 <literal>ngx_keyval_t</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3642 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	3643 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	3644 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3645
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 <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	3648 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	3649 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3650
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3651 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3652 <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	3653 <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	3654 expressed in bytes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3655 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3656
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3657 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3658 <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	3659 <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	3660 expressed in bytes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3661 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3662
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3663 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3664 <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	3665 <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	3666 expressed in milliseconds.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3667 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3668
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3669 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3670 <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	3671 <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	3672 expressed in in seconds.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3673 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3674
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3675 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3676 <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	3677 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	3678 <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	3679 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3680
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3681 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3682 <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	3683 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	3684 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	3685 <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	3686 integer values.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3687 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3688
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3689 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3690 <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	3691 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	3692 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	3693 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	3694 <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	3695 mask values.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3696 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3697
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3698 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3699 <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	3700 <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	3701 For details, see the documentation for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3702 <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	3703 proxy_temp_path</link> directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3704 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3705
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3706 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3707 <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	3708 permissions mask.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3709 For details, see the documentation for the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3710 <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	3711 proxy_store_access</link> directive.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3712 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3713
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3714 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3715
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3716 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3717
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3718 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3719 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	3720 passed to the directory handler.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3721 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	3722 <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	3723 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	3724 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	3725 <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	3726
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3727 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3728 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3729 <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	3730 <literal>http</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3731 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3732
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 <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	3735 <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	3736 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3737
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 <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	3740 <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	3741 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3742
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 <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	3745 <literal>stream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3746 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3747
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 <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	3750 <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	3751 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3752
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 <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	3755 <literal>mail</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3756 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3757
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3758 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3759 <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	3760 <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	3761 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3762
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3763 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3764
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3765 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3766
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3767 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3768 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	3769 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	3770 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	3771 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3772
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3773 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3774 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	3775 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	3776 additional data to the main handler.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3777 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	3778 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	3779 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3780 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	3781 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	3782 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3783 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	3784 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	3785 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	3786 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3787
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3788 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3789
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3790 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3791
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3792
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3793 <section name="HTTP" id="http">
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3796 <section name="Connection" id="http_connection">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3797
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3798 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3799 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	3800 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3801
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3802 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3803
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3804 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3805 <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	3806 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	3807 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	3808 to wrap the newly accepted client socket.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3809 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	3810 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	3811 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3812
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3813 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3814 <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	3815 the HTTP connection.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3816 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	3817 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	3818 <literal>data</literal> field.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3819 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	3820 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	3821 this stage as well.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3822 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3823
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3824 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3825 <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	3826 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	3827 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	3828 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	3829 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3830
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3831 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3832 <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	3833 reads client request line.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3834 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	3835 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	3836 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	3837 <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	3838 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	3839 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	3840 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	3841 directive.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3842 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3843
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3844 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3845 <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	3846 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	3847 the client request header.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3848 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3849
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3850 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3851 <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	3852 is completely read and parsed.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3853 This function runs request phases from
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3854 <literal>NGX_HTTP_POST_READ_PHASE</literal> to
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3855 <literal>NGX_HTTP_CONTENT_PHASE</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3856 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	3857 chain.
1979 ff28ca78bef3 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1976 diff changeset	3858 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	3859 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	3860 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3861
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3862 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3863 <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	3864 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	3865 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	3866 response.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3867 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	3868 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	3869 sending outstanding data.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3870 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3871
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3872 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3873 <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	3874 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	3875 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	3876 <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	3877 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	3878 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	3879 request and the connection.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3880 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3881
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3882 </list>
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>
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3887 <section name="Request" id="http_request">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3888
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 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	3891 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	3892 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3893
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3894 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3895
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3896 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3897
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3898 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3899 <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	3900 client connection object.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3901 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	3902 one main request and its subrequests.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3903 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	3904 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3905
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3906 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3907 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	3908 <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	3909 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	3910 connection.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3911 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	3912 output its response to the client.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3913 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	3914 output.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3915 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3916
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3917 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3918
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3919 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3920
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3921 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3922 <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	3923 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	3924 (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	3925 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	3926 <literal>ctx_index</literal> position.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3927 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	3928 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3929
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3930 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3931
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3932 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3933 <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	3934 the <literal>module</literal>'s context
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3935 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3936
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3937 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3938 <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	3939 as the <literal>module</literal>'s context
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3940 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3941
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3942 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3943
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3944 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3945
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3946 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3947 <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	3948 <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	3949 configurations.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3950 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	3951 positions.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3952 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3953
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3954 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3955 <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	3956 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	3957 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	3958 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	3959 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	3960 <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	3961 active request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3962 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3963
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 <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	3966 upstream response.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3967 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3968
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3969 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3970 <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	3971 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3972
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3973 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3974 <literal>pool</literal> — Request pool.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3975 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	3976 the request is deleted.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3977 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	3978 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	3979 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3980
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 <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	3983 header is read.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3984 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3985
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3986 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3987 <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	3988 output HTTP headers objects.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3989 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	3990 <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	3991 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	3992 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	3993 <literal>status</literal> etc.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3994 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3995
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3996 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3997 <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	3998 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	3999
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 <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	4002 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	4003 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4004
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4005 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4006 <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	4007 representation of the client HTTP request method.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4008 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	4009 <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	4010 <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	4011 <literal>NGX_HTTP_POST</literal>, etc.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4012 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4013
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 <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	4016 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	4017 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4018
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4019 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4020 <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	4021 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	4022 <literal>NGX_HTTP_VERSION_11</literal>, etc.).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4023 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4024
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 <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	4027 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	4028 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4029
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 <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	4032 and URI in the original client request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4033 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4034
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4035 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4036 <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	4037 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	4038 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	4039 normalization.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4040 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	4041 are performed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4042 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4043
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4044 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4045 <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	4046 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	4047 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	4048 request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4049 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4050
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4051 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4052 <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	4053 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4054
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4055 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4056 <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	4057 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	4058 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	4059 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	4060 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4061
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4062 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4063 <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	4064 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	4065 Unused for main requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4066 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4067
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4068 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4069
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4070 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4071 <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	4072 resumed, which is done by calling the request's
1932 937e03180281 Fixed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1929 diff changeset	4073 <literal>write_event_handler</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4074 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	4075 request phases and then produces the output.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4076 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4077
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4078 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4079 A request is usually posted by the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4080 <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	4081 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	4082 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	4083 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	4084 connection's active request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4085 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	4086 which can lead to new posted requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4087 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	4088 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4089
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4090 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4091
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4092 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4093 <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	4094 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4095
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4096 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4097 <literal>ncaptures</literal>, <literal>captures</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4098 <literal>captures_data</literal> — Regex captures produced
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4099 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	4100 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	4101 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	4102 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	4103 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	4104 <literal>captures</literal> holds captures boundaries and
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4105 <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	4106 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	4107 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	4108 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4109
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4110 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4111 <literal>count</literal> — Request reference counter.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4112 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	4113 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	4114 To decrease the counter, call
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4115 <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	4116 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	4117 increment the counter.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4118 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4119
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4120 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4121 <literal>subrequests</literal> — Current subrequest nesting level.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4122 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	4123 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	4124 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	4125 <literal>NGX_HTTP_MAX_SUBREQUESTS</literal> constant.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4126 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4127
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4128 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4129 <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	4130 the request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4131 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	4132 <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	4133 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	4134 an error is generated.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4135 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	4136 changes.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4137 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4138
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4139 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4140 <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	4141 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	4142 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	4143 thread operations) and active cache lock.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4144 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4145
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4146 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4147 <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	4148 output produced by the request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4149 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	4150 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	4151 lack of free output buffers etc.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4152 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	4153 pending the flush.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4154 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4155
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4156 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4157 <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	4158 require a body.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4159 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	4160 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4161
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4162 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4163 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4164 <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	4165 keepalive is supported.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4166 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	4167 <header>Connection</header> header.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4168 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4169 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4170
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 <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	4173 has already been sent by the request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4174 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4175
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4176 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4177 <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	4178 is internal.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4179 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	4180 redirect or be a subrequest.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4181 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	4182 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4183
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 <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	4186 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	4187 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4188
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 <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	4191 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	4192 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4193
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4194 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4195 <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	4196 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	4197 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	4198 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	4199 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4200
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4201 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4202 <literal>main_filter_need_in_memory</literal>,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4203 <literal>filter_need_in_memory</literal> — Flags
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4204 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	4205 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	4206 sendfile is enabled.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4207 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	4208 set them.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4209 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	4210 <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	4211 request output come in memory buffers.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4212 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	4213 <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	4214 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	4215 while sending output.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4216 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4217
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4218 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4219 <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	4220 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	4221 file buffers.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4222 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	4223 it's sent.</listitem>
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4224
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4225 </list>
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>
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4230 <section name="Configuration" id="http_conf">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4231
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4232 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4233 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	4234 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4235
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4236 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4237
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4238 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4239 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	4240 Functions as global settings for a module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4241 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4242
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 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	4245 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	4246 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4247
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4248 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4249 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	4250 <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	4251 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	4252 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4253
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4254 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4255
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4256 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4257 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	4258 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	4259 and merge them.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4260 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	4261 configuration for a module.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4262 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	4263 unsigned integer.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4264 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4265
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4266 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4267 typedef struct {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4268 ngx_uint_t foo;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4269 } ngx_http_foo_loc_conf_t;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4270
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4271
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4272 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	4273 NULL, /* preconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4274 NULL, /* postconfiguration */
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 main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4277 NULL, /* init main 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 NULL, /* create server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4280 NULL, /* merge server 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 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	4283 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	4284 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4285
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 static void *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4288 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	4289 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4290 ngx_http_foo_loc_conf_t *conf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4291
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4292 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	4293 if (conf == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4294 return NULL;
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4297 conf->foo = NGX_CONF_UNSET_UINT;
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 return conf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4300 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4301
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 static char *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4304 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	4305 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4306 ngx_http_foo_loc_conf_t *prev = parent;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4307 ngx_http_foo_loc_conf_t *conf = child;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4308
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4309 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	4310 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4311 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4312
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4313 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4314 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	4315 function creates a new configuration structure, and
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4316 <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	4317 configuration from a higher level.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4318 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	4319 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	4320 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	4321 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	4322 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	4323 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	4324 Eventually configurations are merged down.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4325 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	4326 <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	4327 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	4328 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	4329 <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	4330 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	4331 provided an explicit value.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4332 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	4333 <literal>src/core/ngx_conf_file.h</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4334 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4335
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4336 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4337 The following macros are available.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4338 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	4339 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	4340 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4341
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4342 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4343
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4344 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4345 <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	4346 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4347
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4348 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4349 <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	4350 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4351
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4352 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4353 <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	4354 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4355
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4356 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4357
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4358 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4359 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	4360 standard nginx core module
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4361 <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	4362 and replaces the location content handler kept
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4363 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	4364 </para>
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 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4367 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	4368
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4369
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4370 static ngx_command_t ngx_http_foo_commands[] = {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4371
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4372 { ngx_string("foo"),
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4373 NGX_HTTP_LOC_CONF\|NGX_CONF_NOARGS,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4374 ngx_http_foo,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4375 0,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4376 0,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4377 NULL },
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 ngx_null_command
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4380 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4381
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 static char *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4384 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	4385 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4386 ngx_http_core_loc_conf_t *clcf;
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 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	4389 clcf->handler = ngx_http_bar_handler;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4390
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4391 return NGX_CONF_OK;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4392 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4393 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4394
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4395 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4396 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	4397 modules at runtime.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4398 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4399
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4400 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4401
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4402 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4403 <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	4404 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4405
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4406 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4407 <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	4408 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4409
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4410 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4411 <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	4412 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4413
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4414 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4415
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4416 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4417 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	4418 <literal>ngx_http_request_t</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4419 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	4420 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	4421 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	4422 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	4423 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	4424 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	4425 runtime.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4426 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4427
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4428 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4429 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4430 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	4431 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4432 ngx_http_foo_loc_conf_t *flcf;
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 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	4435
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 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4438 </programlisting>
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>
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4443 <section name="Phases" id="http_phases">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4444
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4445 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4446 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	4447 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	4448 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	4449 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	4450 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	4451 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	4452 once the request reaches the phase.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4453 Following is the list of nginx HTTP phases.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4454 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4455
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4456 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4457
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4458 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4459 <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	4460 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	4461 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	4462 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	4463 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4464
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4465 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4466 <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	4467 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	4468 (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	4469 The
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4470 <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	4471 installs its handler at this phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4472 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4473
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4474 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4475 <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	4476 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	4477 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	4478 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	4479 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	4480 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	4481 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	4482 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4483
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4484 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4485 <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	4486 <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	4487 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	4488 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4489
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4490 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4491 <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	4492 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	4493 during a rewrite.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4494 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	4495 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	4496 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	4497 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4498
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4499 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4500 <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	4501 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	4502 The standard nginx modules
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4503 <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	4504 </link> and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4505 <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	4506 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	4507 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4508
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4509 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4510 <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	4511 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	4512 Standard nginx modules such as
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4513 <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	4514 <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	4515 </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	4516 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	4517 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	4518 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	4519 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	4520 authorizes the client.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4521 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4522
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4523 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4524 <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	4525 <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	4526 directive is processed.
2146 c07cd947402f Development guide: typo fixed. Andrei Belov <defan@nginx.com> parents: 2081 diff changeset	4527 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	4528 request is finalized.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4529 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	4530 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4531
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4532 <listitem>
2024 a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4533 <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	4534 prior to generating content.
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4535 Standard modules such as
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4536 <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	4537 ngx_http_try_files_module</link> and
a8d1a748324f DevGuide: mentioned the precontent phase. Roman Arutyunyan <arut@nginx.com> parents: 2023 diff changeset	4538 <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	4539 register their handlers at this phase.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4540 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4541
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4542 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4543 <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	4544 is normally generated.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4545 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	4546 including
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4547 <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	4548 <literal>ngx_http_static_module</literal>.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4549 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	4550 the output.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4551 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	4552 If the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4553 <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	4554 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	4555 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	4556 are ignored.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4557 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4558
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4559 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4560 <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	4561 is performed.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4562 Currently, only the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4563 <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	4564 registers its handler
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4565 at this stage for access logging.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4566 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	4567 before freeing the request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4568 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4569
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4570 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4571
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4572 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4573 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	4574 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4575
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4576 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4577 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	4578 NULL, /* preconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4579 ngx_http_foo_init, /* postconfiguration */
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 main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4582 NULL, /* init main 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 server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4585 NULL, /* merge server 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 NULL, /* create location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4588 NULL /* merge location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4589 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4590
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 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4593 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	4594 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4595 ngx_str_t *ua;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4596
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4597 ua = r->headers_in->user_agent;
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 if (ua == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4600 return NGX_DECLINED;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4601 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4602
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4603 /* reject requests with "User-Agent: foo" */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4604 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	4605 return NGX_HTTP_FORBIDDEN;
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 return NGX_DECLINED;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4609 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4610
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 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4613 ngx_http_foo_init(ngx_conf_t *cf)
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 ngx_http_handler_pt *h;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4616 ngx_http_core_main_conf_t *cmcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4617
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4618 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	4619
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4620 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	4621 if (h == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4622 return NGX_ERROR;
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4625 *h = ngx_http_foo_handler;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4626
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4627 return NGX_OK;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4628 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4629 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4630
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4631 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4632 Phase handlers are expected to return specific codes:
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4633 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4634
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4635 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4636
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4637 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4638 <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	4639 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4640
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4641 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4642 <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	4643 phase.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4644 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	4645 move to the next phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4646 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4647
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4648 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4649 <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	4650 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	4651 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	4652 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	4653 <literal>ngx_http_core_run_phases()</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4654 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4655
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4656 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4657 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	4658 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	4659 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	4660 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4661
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4662 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4663
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4664 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4665 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	4666 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	4667 <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	4668 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	4669 finalization code.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4670 At the access phase, in
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4671 <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	4672 mode,
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4673 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	4674 <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	4675 <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	4676 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	4677 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	4678 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4679
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4680 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4681
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	4682
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4683 <section name="Variables" id="http_variables">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4684
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4685 <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	4686
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4687 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4688 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	4689 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	4690 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	4691 to the configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4692 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	4693 <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	4694 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4695 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	4696 ngx_int_t index;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4697
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4698 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	4699 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4700 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	4701 <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	4702 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	4703 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	4704 configuration for future use.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4705 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4706
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4707 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4708 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	4709 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	4710 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	4711 <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	4712 the variable value:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4713 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4714 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	4715
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4716 typedef struct {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4717 unsigned len:28;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4718
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4719 unsigned valid:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4720 unsigned no_cacheable:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4721 unsigned not_found:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4722 unsigned escape:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4723
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4724 u_char *data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4725 } ngx_variable_value_t;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4726 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4727 where:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4728 <list type="bullet">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4729
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4730 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4731 <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	4732 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4733
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4734 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4735 <literal>data</literal> — The value itself
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4736 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4737
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4738 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4739 <literal>valid</literal> — The value is valid
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4740 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4741
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4742 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4743 <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	4744 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	4745 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	4746 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	4747 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4748
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4749 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4750 <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	4751 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4752
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4753 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4754 <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	4755 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	4756 </listitem>
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 </list>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4759 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4760
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4761 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4762 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	4763 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	4764 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	4765 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	4766 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	4767 that identifies it.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4768 An example of typical usage:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4769 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4770 ngx_http_variable_value_t *v;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4771
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4772 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	4773
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4774 if (v == NULL \|\| v->not_found) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4775 /* 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	4776 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4777 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4778
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4779 /* some meaningful value is found */
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4780 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4781 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	4782 <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	4783 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	4784 non-cacheable variables.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4785 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4786
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4787 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4788 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	4789 name is not known at configuration time.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4790 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	4791 <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	4792 is available.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4793 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	4794 <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	4795 from the name.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4796 </para>
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>
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
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4801 <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	4802
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4803 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4804 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	4805 function.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4806 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	4807 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	4808
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4809 <list type="bullet">
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4810 <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	4811 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	4812 the same name.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4813 This allows the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4814 <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	4815 to override variables.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4816 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4817
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4818 <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	4819 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	4820 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4821
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4822 <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	4823 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	4824 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	4825 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	4826 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4827
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4828 <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	4829 variable is a prefix.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4830 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	4831 of a specific variable.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4832 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	4833 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	4834 of a specific argument.
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4835 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4836
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4837 </list>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4838
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4839 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	4840 <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	4841 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4842 struct ngx_http_variable_s {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4843 ngx_str_t name;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4844 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	4845 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	4846 uintptr_t data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4847 ngx_uint_t flags;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4848 ngx_uint_t index;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4849 };
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4850 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4851
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4852 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	4853 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	4854 <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	4855 <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	4856 the variable.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4857 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4858
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4859 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4860 Usually, a null-terminated static array of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4861 <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	4862 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	4863 into the configuration, for example:
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4864 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4865 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	4866
2009 9b7302e3b21f DevGuide: fixed variables example. Vladimir Homutov <vl@nginx.com> parents: 2008 diff changeset	4867 { 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	4868
2023 ec34516cbd1b DevGuide: documented macros for null variables. Vladimir Homutov <vl@nginx.com> parents: 2009 diff changeset	4869 ngx_http_null_variable
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4870 };
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 static ngx_int_t
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4873 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	4874 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4875 ngx_http_variable_t var, v;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4876
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4877 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	4878 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	4879 if (var == NULL) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4880 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4881 }
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 var->get_handler = v->get_handler;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4884 var->data = v->data;
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
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4887 return NGX_OK;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4888 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4889 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4890 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	4891 the <literal>preconfiguration</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4892 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	4893 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	4894 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4895
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4896 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4897 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	4898 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	4899 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4900 static ngx_int_t
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4901 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	4902 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	4903 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4904 u_char *p;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4905
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4906 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	4907 if (p == NULL) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4908 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4909 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4910
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4911 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	4912 v->valid = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4913 v->no_cacheable = 0;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4914 v->not_found = 0;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4915 v->data = p;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4916
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4917 return NGX_OK;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4918 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4919 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4920 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	4921 (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	4922 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	4923 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	4924 <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	4925 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4926
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4927 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4928 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	4929 referenced by the variable.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	4930 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	4931 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	4932 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4933 ...
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4934 { 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	4935 ngx_http_variable_request_get_size,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4936 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	4937 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	4938 ...
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4939
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4940 static void
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4941 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	4942 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	4943 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4944 ssize_t s, *sp;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4945 ngx_str_t val;
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 val.len = v->len;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4948 val.data = v->data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4949
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4950 s = ngx_parse_size(&val);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4951
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4952 if (s == NGX_ERROR) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4953 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	4954 "invalid size \"%V\"", &val);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4955 return;
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
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4958 sp = (ssize_t ) ((char ) r + data);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4959
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4960 *sp = s;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4961
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4962 return;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4963 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4964 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4965
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4966 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4967
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4968 </section>
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>
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
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4973 <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	4974
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 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	4977 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	4978 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4979
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4980 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4981 The complex value description in
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4982 <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	4983 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	4984 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	4985
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4986 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4987 ngx_str_t *value;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4988 ngx_http_complex_value_t cv;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4989 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	4990
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4991 value = cf->args->elts; /* directive arguments */
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4992
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4993 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	4994
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4995 ccv.cf = cf;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4996 ccv.value = &value[1];
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4997 ccv.complex_value = &cv;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4998 ccv.zero = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4999 ccv.conf_prefix = 1;
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 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	5002 return NGX_CONF_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5003 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5004 </programlisting>
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 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	5007 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	5008
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5009 <list type="bullet">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5010
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5011 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5012 <literal>cf</literal> — Configuration pointer
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5013 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5014
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5015 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5016 <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	5017 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5018
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5019 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5020 <literal>complex_value</literal> — Compiled value (output)
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5021 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5022
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5023 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5024 <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	5025 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5026
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5027 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5028 <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	5029 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	5030 configuration)
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5031 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5032
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5033 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5034 <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	5035 (the normal nginx installation prefix)
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5036 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5037
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5038 </list>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5039 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	5040 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	5041 dealing with filenames.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5042 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5043
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5044 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5045 Upon successful compilation, <literal>cv.lengths</literal>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5046 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	5047 in the expression.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5048 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	5049 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	5050 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5051
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5052 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5053 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	5054 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	5055 declaration itself.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5056 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5057
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5058 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5059 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	5060 <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	5061 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5062 ngx_str_t res;
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 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	5065 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5066 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5067 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5068 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	5069 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	5070 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	5071 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5072
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5073 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5074
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	5075
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5076 <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	5077
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5078 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5079 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	5080 <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	5081 structure.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5082 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	5083 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	5084 <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	5085 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	5086 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	5087 request.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5088 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	5089 <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	5090 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	5091 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	5092 <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	5093 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	5094 configured for the server.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5095 The
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5096 <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	5097 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	5098 <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	5099 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	5100 directive and send the request back
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5101 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	5102 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	5103 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5104
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5105 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5106 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	5107 calling one of
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5108 <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	5109 <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	5110 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5111
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5112 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5113 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	5114 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	5115 <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	5116 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	5117 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	5118 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	5119 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5120
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 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	5123 arguments.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5124 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5125
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5126 <programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5127 ngx_int_t
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5128 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	5129 {
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5130 ngx_str_t uri, args;
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 ngx_str_set(&uri, "/foo");
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5133 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	5134
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5135 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	5136 }
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5137 </programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5138
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5139 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5140 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	5141 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	5142 argument.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5143 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	5144 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	5145 <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	5146 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5147
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5148 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5149 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	5150 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5151
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5152 <programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5153 ngx_int_t
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5154 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	5155 {
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5156 ngx_str_t name;
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5157
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5158 ngx_str_set(&name, "foo");
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5159
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5160 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	5161 }
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5162 </programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5163
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5164 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5165 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	5166 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	5167 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	5168 <literal>ctx</literal> field.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5169 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	5170 location configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5171 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	5172 erased by both redirect functions.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5173 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5174
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5175 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5176 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	5177 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	5178 <literal>count</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5179 For consistent request reference counting, call
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5180 <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	5181 request.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5182 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	5183 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5184
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5185 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5186 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	5187 <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	5188 locations.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5189 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	5190 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5191
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5192 </section>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5193
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5194
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5195 <section name="Subrequests" id="http_subrequests">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5196
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5197 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5198 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	5199 possibly mixed with other data.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5200 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	5201 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	5202 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	5203 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	5204 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	5205 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	5206 a group of requests.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5207 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5208
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5209 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5210 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	5211 phase.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5212 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	5213 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	5214 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5215
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5216 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5217 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	5218 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	5219 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	5220 by the parent request.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5221 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5222
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5223 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5224 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	5225 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	5226 <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	5227 connection object.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5228 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	5229 to output its buffers to the client.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5230 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	5231 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	5232 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	5233 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	5234 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5235
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5236 <list type="bullet">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5237
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5238 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5239 Initially, the main request is active.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5240 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5241
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5242 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5243 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	5244 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5245
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5246 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5247 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	5248 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	5249 are sent.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5250 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5251
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5252 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5253 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	5254 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5255
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5256 </list>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5257
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5258 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5259 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	5260 <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	5261 <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	5262 <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	5263 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	5264 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	5265 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	5266 <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	5267 The following flags are available:
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5268 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5269
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5270 <list type="bullet">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5271
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5272 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5273 <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	5274 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	5275 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	5276 modules.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5277 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	5278 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	5279 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5280
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5281 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5282 <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	5283 <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	5284 it is finalized.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5285 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	5286 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5287
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5288 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5289 <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	5290 clone of its parent.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5291 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	5292 parent request.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5293 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5294
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5295 </list>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5296
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5297 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5298 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	5299 of <literal>/foo</literal>.
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5300 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5301
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5302 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5303 ngx_int_t rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5304 ngx_str_t uri;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5305 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5306
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
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5309 ngx_str_set(&uri, "/foo");
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5310
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5311 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	5312 if (rc == NGX_ERROR) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5313 /* error */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5314 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5315 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5316
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 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	5319 subrequest.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5320 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5321
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5322 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5323 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5324 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	5325 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5326 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5327 ngx_http_post_subrequest_t *ps;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5328
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5329 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	5330 if (ps == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5331 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5332 }
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 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	5335 ps->data = "foo";
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 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	5338 NGX_HTTP_SUBREQUEST_CLONE);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5339 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5340
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 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5343 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	5344 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5345 char msg = (char ) data;
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 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	5348 "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	5349
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5350 return rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5351 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5352 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5353
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5354 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5355 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	5356 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	5357 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	5358 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	5359 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	5360 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	5361 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	5362 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	5363 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5364
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5365 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5366 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5367 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	5368 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5369 ngx_int_t rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5370 ngx_buf_t *b;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5371 ngx_uint_t last;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5372 ngx_chain_t *cl, out;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5373 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5374 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	5375
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5376 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	5377 if (ctx == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5378 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	5379 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5380
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5381 last = 0;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5382
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5383 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	5384 if (cl->buf->last_buf) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5385 cl->buf->last_buf = 0;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5386 cl->buf->last_in_chain = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5387 cl->buf->sync = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5388 last = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5389 }
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
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5392 /* Output explicit output buffers */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5393
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5394 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	5395
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5396 if (rc == NGX_ERROR \|\| !last) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5397 return rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5398 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5399
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5400 /*
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5401 * 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	5402 * 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	5403 * 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	5404 */
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 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	5407 return NGX_ERROR;
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
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5410 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	5411
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5412 /* 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	5413
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5414 b = ngx_calloc_buf(r->pool);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5415 if (b == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5416 return NGX_ERROR;
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
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5419 b->last_buf = 1;
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 out.buf = b;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5422 out.next = NULL;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5423
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5424 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	5425 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5426 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5427
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5428 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5429 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	5430 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	5431 ngx_http_auth_request_module</link> module
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5432 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	5433 To disable output at this point, the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5434 <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	5435 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	5436 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	5437 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	5438 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5439
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5440 </section>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5441
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5442
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5443 <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	5444
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5445 <para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5446 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	5447 <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	5448 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	5449 are sent to the filter chain.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5450 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	5451 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	5452 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	5453 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	5454 to finish sending the output.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5455 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	5456 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	5457 </para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5458
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 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	5461 following <literal>rc</literal> values:
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5462 </para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5463
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5464 <list type="bullet">
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5465
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5466 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5467 <literal>NGX_DONE</literal> - Fast finalization.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5468 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	5469 reaches zero.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5470 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	5471 is destroyed.
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5472 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5473
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5474 <listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5475 <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	5476 (<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	5477 (<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	5478 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	5479 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5480
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5481 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5482 <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	5483 <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	5484 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	5485 (<literal>300</literal>) - Special response finalization.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5486 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	5487 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	5488 <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	5489 is configured for the code.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5490 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5491
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5492 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5493 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	5494 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	5495 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	5496 is decremented.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5497 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	5498 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	5499 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	5500 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	5501 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5502
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5503 </list>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5504
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5505 </section>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5506
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5507
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5508 <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	5509
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5510 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5511 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	5512 <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	5513 <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	5514 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	5515 <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	5516 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	5517 body.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5518 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	5519 Normally, the content handler makes the call.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5520 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5521
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5522 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5523 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	5524 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	5525 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	5526 <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	5527 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	5528 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5529
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5530 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5531 The function
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5532 <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	5533 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	5534 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	5535 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	5536 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	5537 immediately.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5538 The function
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5539 <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	5540 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	5541 <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	5542 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	5543 chain.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5544 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	5545 specified by the
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5546 <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	5547 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	5548 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5549
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5550 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5551 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	5552 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5553
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5554 <programlisting>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5555 ngx_int_t
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5556 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	5557 {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5558 ngx_int_t rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5559
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5560 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	5561
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5562 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	5563 /* error */
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5564 return rc;
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 return NGX_DONE;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5568 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5569
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 void
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5572 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	5573 {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5574 off_t len;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5575 ngx_buf_t *b;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5576 ngx_int_t rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5577 ngx_chain_t *in, out;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5578
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5579 if (r->request_body == NULL) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5580 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	5581 return;
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
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5584 len = 0;
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 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	5587 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	5588 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5589
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5590 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	5591 if (b == NULL) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5592 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	5593 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5594 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5595
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5596 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	5597 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	5598 b->last_in_chain = 1;
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 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	5601 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	5602
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5603 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	5604
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5605 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	5606 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	5607 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5608 }
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 out.buf = b;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5611 out.next = NULL;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5612
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5613 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	5614
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5615 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	5616 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5617 </programlisting>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5618
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5619 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5620 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	5621 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5622
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5623 <list type="bullet">
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5624
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5625 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5626 <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	5627 buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5628 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5629
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 <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	5632 even if fits in the memory buffer.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5633 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5634
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5635 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5636 <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	5637 immediately after creation.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5638 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	5639 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5640
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5641 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5642 <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	5643 request is finalized.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5644 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	5645 but was not moved for some reason.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5646 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5647
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 <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	5650 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	5651 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5652
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 <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	5655 log file errors.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5656 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5657
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5658 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5659 <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	5660 buffering.
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5661 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5662
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5663 </list>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5664
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5665 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5666 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	5667 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	5668 In this mode, after calling
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5669 <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	5670 <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	5671 To read the next part, call the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5672 <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	5673 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	5674 <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	5675 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	5676 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	5677 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	5678 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	5679 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5680
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5681 </section>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5682
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5683
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5684 <section name="Response" id="http_response">
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5685
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5686 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5687 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	5688 the optional response body.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5689 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	5690 written to the client socket.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5691 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	5692 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	5693 </para>
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5696 <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	5697
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5698 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5699 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	5700 function sends the output header.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5701 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	5702 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	5703 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	5704 must always be set.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5705 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	5706 <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	5707 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	5708 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	5709 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	5710 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	5711 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5712
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5713 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5714 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5715 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	5716 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5717 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5718 ngx_table_elt_t *h;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5719
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5720 /* send header */
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 r->headers_out.status = NGX_HTTP_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5723 r->headers_out.content_length_n = 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5724
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5725 /* X-Foo: foo */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5726
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5727 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	5728 if (h == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5729 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5730 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5731
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5732 h->hash = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5733 ngx_str_set(&h->key, "X-Foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5734 ngx_str_set(&h->value, "foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5735
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5736 rc = ngx_http_send_header(r);
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 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	5739 return rc;
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 /* send body */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5743
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 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5746 </programlisting>
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>
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5751 <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	5752
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5753 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5754 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	5755 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	5756 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	5757 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	5758 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	5759 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	5760 <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	5761 <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	5762 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5763
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5764 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5765 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	5766 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	5767 at configuration time.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5768 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	5769 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	5770 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5771
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5772 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5773 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	5774 "<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	5775 <literal>200</literal>.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5776 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5777
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5778 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5779 #include <ngx_config.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5780 #include <ngx_core.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5781 #include <ngx_http.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5782
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 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	5785 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	5786
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5787
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5788 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	5789 NULL, /* preconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5790 ngx_http_foo_header_filter_init, /* postconfiguration */
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 main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5793 NULL, /* init main 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 server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5796 NULL, /* merge server 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 NULL, /* create location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5799 NULL /* merge location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5800 };
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5801
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5802
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5803 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	5804 NGX_MODULE_V1,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5805 &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	5806 NULL, /* module directives */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5807 NGX_HTTP_MODULE, /* module type */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5808 NULL, /* init master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5809 NULL, /* init module */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5810 NULL, /* init process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5811 NULL, /* init thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5812 NULL, /* exit thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5813 NULL, /* exit process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5814 NULL, /* exit master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5815 NGX_MODULE_V1_PADDING
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5816 };
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_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	5820
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 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5823 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	5824 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5825 ngx_table_elt_t *h;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5826
1971 5fb870087b76 Fixed typo and removed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1970 diff changeset	5827 /*
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5828 * 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	5829 * to every HTTP 200 response
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5830 */
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 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	5833 return ngx_http_next_header_filter(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5834 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5835
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5836 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	5837 if (h == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5838 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5839 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5840
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5841 h->hash = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5842 ngx_str_set(&h->key, "X-Foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5843 ngx_str_set(&h->value, "foo");
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 return ngx_http_next_header_filter(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5846 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5847
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 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5850 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	5851 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5852 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	5853 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	5854
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5855 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5856 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5857 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5858
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5859 </section>
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>
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5864 <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	5865
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5866 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5867 To send the response body, call the
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5868 <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	5869 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	5870 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	5871 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	5872 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5873
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5874 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5875 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	5876 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	5877 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	5878 of the output.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5879 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	5880 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	5881 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5882
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5883 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5884 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5885 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	5886 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5887 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5888 ngx_buf_t *b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5889 ngx_chain_t out;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5890
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5891 /* send header */
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 r->headers_out.status = NGX_HTTP_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5894 r->headers_out.content_length_n = 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5895
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5896 rc = ngx_http_send_header(r);
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 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	5899 return rc;
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5902 /* send body */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5903
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5904 b = ngx_calloc_buf(r->pool);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5905 if (b == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5906 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5907 }
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->last_buf = (r == r->main) ? 1: 0;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5910 b->last_in_chain = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5911
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5912 b->memory = 1;
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 b->pos = (u_char *) "foo";
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5915 b->last = b->pos + 3;
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 out.buf = b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5918 out.next = NULL;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5919
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5920 return ngx_http_output_filter(r, &out);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5921 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5922 </programlisting>
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>
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5927 <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	5928
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5929 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5930 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	5931 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	5932 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	5933 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	5934 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	5935 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5936
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5937 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5938 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	5939 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	5940 the next handler.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5941 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	5942 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	5943 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	5944 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	5945 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	5946 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	5947 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5948
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5949 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	5950 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	5951 bytes in the body.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5952 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	5953 used in the access log.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5954 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5955
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5956 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5957 #include <ngx_config.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5958 #include <ngx_core.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5959 #include <ngx_http.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5960
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5961
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5962 typedef struct {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5963 off_t count;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5964 } ngx_http_counter_filter_ctx_t;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5965
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5966
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5967 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	5968 ngx_chain_t *in);
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_variable(ngx_http_request_t *r,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5970 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	5971 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	5972 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	5973
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5974
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5975 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	5976 ngx_http_counter_add_variables, /* preconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5977 ngx_http_counter_filter_init, /* postconfiguration */
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 main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5980 NULL, /* init main 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 server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5983 NULL, /* merge server 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 NULL, /* create location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5986 NULL /* merge location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5987 };
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5988
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5989
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5990 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	5991 NGX_MODULE_V1,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5992 &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	5993 NULL, /* module directives */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5994 NGX_HTTP_MODULE, /* module type */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5995 NULL, /* init master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5996 NULL, /* init module */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5997 NULL, /* init process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5998 NULL, /* init thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5999 NULL, /* exit thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6000 NULL, /* exit process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6001 NULL, /* exit master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6002 NGX_MODULE_V1_PADDING
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6003 };
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6006 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	6007
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6008 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	6009
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 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6012 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	6013 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6014 ngx_chain_t *cl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6015 ngx_http_counter_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6016
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6017 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	6018 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6019 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	6020 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6021 return NGX_ERROR;
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 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	6025 }
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 for (cl = in; cl; cl = cl->next) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6028 ctx->count += ngx_buf_size(cl->buf);
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 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	6032 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6033
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6034
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6035 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6036 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	6037 uintptr_t data)
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 u_char *p;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6040 ngx_http_counter_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6041
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6042 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	6043 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6044 v->not_found = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6045 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6046 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6047
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6048 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	6049 if (p == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6050 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6051 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6052
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6053 v->data = p;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6054 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	6055 v->valid = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6056 v->no_cacheable = 0;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6057 v->not_found = 0;
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 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6060 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6061
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 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6064 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	6065 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6066 ngx_http_variable_t *var;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6067
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6068 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	6069 if (var == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6070 return NGX_ERROR;
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6073 var->get_handler = ngx_http_counter_variable;
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 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6076 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6077
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 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6080 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	6081 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6082 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	6083 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	6084
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6085 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6086 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6087 </programlisting>
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>
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6092 <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	6093
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6094 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6095 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	6096 position in the filter order.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6097 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	6098 modules.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6099 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	6100 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	6101 them.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6102 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	6103 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	6104 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	6105 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6106
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6107 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6108 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	6109 <literal>HTTP_AUX_FILTER_MODULES</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6110 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	6111 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	6112 <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	6113 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6114
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6115 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6116 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	6117 for a module with just
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6118 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	6119 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6120
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6121 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6122 ngx_module_type=HTTP_AUX_FILTER
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6123 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	6124 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	6125
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6126 . auto/module
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6127 </programlisting>
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>
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6132 <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	6133
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6134 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6135 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	6136 allocated buffers.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6137 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	6138 two buffer chains for this purpose:
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6139 <literal>free</literal> and <literal>busy</literal>.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6140 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	6141 which can be reused.
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6142 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	6143 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	6144 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	6145 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	6146 (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	6147 <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	6148 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	6149 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	6150 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	6151 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	6152 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	6153 <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	6154 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	6155 <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	6156 <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	6157 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	6158 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	6159 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6160
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6161 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6162 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	6163 incoming buffer.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6164 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	6165 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	6166 <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	6167 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	6168 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	6169 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6170
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6171 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6172 typedef struct {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6173 ngx_chain_t *free;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6174 ngx_chain_t *busy;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6175 } ngx_http_foo_filter_ctx_t;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6176
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6179 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	6180 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6181 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6182 ngx_buf_t *b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6183 ngx_chain_t cl, tl, out, *ll;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6184 ngx_http_foo_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6185
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6186 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	6187 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6188 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	6189 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6190 return NGX_ERROR;
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 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	6194 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6195
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6196 /* 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	6197
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6198 ll = &out;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6199
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6200 for (cl = in; cl; cl = cl->next) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6201
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6202 /* 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	6203
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6204 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	6205 if (tl == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6206 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6207 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6208
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6209 b = tl->buf;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6210 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	6211 b->memory = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6212 b->pos = (u_char *) "foo";
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6213 b->last = b->pos + 3;
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 *ll = tl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6216 ll = &tl->next;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6217
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6218 /* append the next incoming buffer */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6219
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6220 tl = ngx_alloc_chain_link(r->pool);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6221 if (tl == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6222 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6223 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6224
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6225 tl->buf = cl->buf;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6226 *ll = tl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6227 ll = &tl->next;
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6230 *ll = NULL;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6231
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6232 /* send the new chain */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6233
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6234 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	6235
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6236 /* update "busy" and "free" chains for reuse */
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 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	6239 (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	6240
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6241 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6242 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6243 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6244
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6245 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6246
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6247
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6248 <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	6249
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6250 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6251 The
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6252 <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	6253 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	6254 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	6255 this functionality.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6256 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	6257 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	6258 </para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6259
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6260 <para>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6261 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	6262 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	6263 modules implement alternative load-balancing methods, but
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6264 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	6265 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	6266 of a server group.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6267 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	6268 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	6269 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6270
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6271 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6272 The
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6273 <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	6274 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	6275 <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	6276 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	6277 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	6278 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	6279 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	6280 upstream configuration.
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6281 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	6282 <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	6283 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	6284 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6285 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	6286 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	6287 void **srv_conf;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6288
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6289 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	6290
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6291 ngx_uint_t flags;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6292 ngx_str_t host;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6293 u_char *file_name;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6294 ngx_uint_t line;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6295 in_port_t port;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6296 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	6297
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6298 #if (NGX_HTTP_UPSTREAM_ZONE)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6299 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	6300 #endif
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6301 };
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6302 </programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6303
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6304 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6305
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6306 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6307 <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	6308 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6309
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6310 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6311 <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	6312 <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	6313 <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	6314 in the <literal>upstream</literal> block.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6315 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6316
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6317 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6318 <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	6319 are supported by the load-balancing method.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6320 The features are configured as parameters of
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6321 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	6322
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6323
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6324 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6325
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6326 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6327 <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	6328 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	6329 <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	6330 and “friends”
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6331 (FastCGI, SCGI, etc.)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6332 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6333
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6334 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6335 <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	6336 parameter is supported
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6337 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6338
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6339 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6340 <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	6341 “<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	6342 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6343
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6344 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6345 <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	6346 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	6347 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6348
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 <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	6351 parameter is supported
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6352 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6353
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 <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	6356 parameter is supported
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6357 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6358
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6359 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6360 <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	6361 “<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	6362 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6363
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6364 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6365
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6366 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6367
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6368 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6369 <literal>host</literal> — Name of the upstream.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6370 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6371
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 <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	6374 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	6375 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6376
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 <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	6379 explicitly defined upstream groups.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6380 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6381
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 <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	6384 if any.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6385 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6386
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6387 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6388 <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	6389 initializing upstream configuration:
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6390
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6391 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6392 typedef struct {
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6393 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	6394 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	6395 void *data;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6396 } ngx_http_upstream_peer_t;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6397 </programlisting>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6398 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	6399 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	6400 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	6401 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	6402 <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	6403
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6404 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6405 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6406 <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	6407 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	6408 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	6409 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	6410 <literal>upstream</literal> block
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6411 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	6412 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	6413 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6414
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6415 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6416 <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	6417 <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	6418 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	6419 <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	6420 is per-upstream).
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6421 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	6422 deal with server selection.
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
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6426 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6427 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6428 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6429
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6430 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6431 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	6432 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	6433 The method is obtained from the
1994 effdf0747a05 Development guide: fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1993 diff changeset	6434 <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	6435 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	6436 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6437 struct ngx_peer_connection_s {
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6438 ...
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6439
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6440 struct sockaddr *sockaddr;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6441 socklen_t socklen;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6442 ngx_str_t *name;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6443
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6444 ngx_uint_t tries;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6445
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6446 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	6447 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	6448 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	6449 void *data;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6450
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6451 #if (NGX_SSL \|\| NGX_COMPAT)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6452 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	6453 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	6454 #endif
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6455
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6456 ...
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6457 };
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6458 </programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6459
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6460 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	6461
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6462 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6463 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6464 <literal>sockaddr</literal>, <literal>socklen</literal>,
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6465 <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	6466 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	6467 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6468
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6469 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6470 <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	6471 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	6472 to the upstream configuration.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6473 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	6474 (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	6475 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6476
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6477 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6478 <literal>tries</literal> — Allowed
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6479 <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	6480 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	6481 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6482
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6483 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6484 <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	6485 <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	6486 - 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	6487 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6488
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6489 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6490
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6491 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6492
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6493 <para>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6494 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	6495 <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	6496 <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	6497 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	6498 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	6499 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6500
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6501 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6502
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6503 <list type="bullet">
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6504 <listitem id="lb_method_get">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6505 <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	6506 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	6507 its address.
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6508 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	6509 <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	6510 <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	6511 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	6512
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6513 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6514
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6515 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6516 <literal>NGX_OK</literal> — Server was selected.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6517 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6518
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6519 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6520 <literal>NGX_ERROR</literal> — Internal error occurred.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6521 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6522
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6523 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6524 <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	6525 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	6526 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	6527 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	6528 handling the maximum number of connections.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6529 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6530
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6531 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6532 <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	6533 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	6534 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	6535 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6536
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6537 <!--
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6538 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6539 <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	6540 processing of this request should be postponed.
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6541 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	6542 </listitem>
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
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6545 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6546
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6547 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6548
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6549 <listitem>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6550 <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	6551 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	6552 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	6553 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	6554
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6555 <list type="bullet">
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6556
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 <literal>NGX_PEER_FAILED</literal> — Attempt was
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6559 <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	6560 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6561
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6562 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6563 <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	6564 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	6565 which are not considered a
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6566 <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	6567 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6568
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6569 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6570 <literal>NGX_PEER_KEEPALIVE</literal> — Currently unused
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6571 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6572
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6573 </list>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6574
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6575 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	6576
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6577 </listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6578
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6579 <listitem>
c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6580 <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	6581 in the OSS version.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6582 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6583
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6584 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6585 <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	6586 <literal>save_session(pc, data)</literal>
2007 c559be34257b DevGuide: language and style fixes, second part. Roman Arutyunyan <arut@nginx.com> parents: 1999 diff changeset	6587 — 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	6588 servers.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6589 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	6590 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6591
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6592 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6593
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6594 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6595
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6596 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6597
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6598 </section>
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6599
2073 75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6600 <section name="Examples" id="examples">
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6601
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6602 <para>
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6603 The
2078 26e547b1022d DevGuide: changed nginx-dev-examples repository. Roman Arutyunyan <arut@nginx.com> parents: 2073 diff changeset	6604 <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	6605 repository provides nginx module examples.
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6606
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6607 </para>
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6608
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6609 </section>
75882a2ca9dd DevGuide: added examples section. Roman Arutyunyan <arut@nginx.com> parents: 2024 diff changeset	6610
2153 ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6611
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6612 <section name="Code style" id="code_style">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6613
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6614 <section name="General rules" id="code_style_general_rules">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6615
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6616 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6617 <list type="bullet">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6618
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6619 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6620 maximum text width is 80 characters
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6621 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6622
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6623 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6624 indentation is 4 spaces
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6625 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6626
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6627 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6628 no tabs, no trailing spaces
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6629 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6630
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6631 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6632 list elements on the same line are separated with spaces
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6633 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6634
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6635 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6636 hexadecimal literals are lowercase
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6637 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6638
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6639 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6640 file names, function and type names, and global variables have the
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6641 <literal>ngx_</literal> or more specific prefix such as
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6642 <literal>ngx_http_</literal> and <literal>ngx_mail_</literal>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6643 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6644
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6645 </list>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6646
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6647 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6648 size_t
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6649 ngx_utf8_length(u_char *p, size_t n)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6650 {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6651 u_char c, *last;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6652 size_t len;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6653
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6654 last = p + n;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6655
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6656 for (len = 0; p < last; len++) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6657
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6658 c = *p;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6659
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6660 if (c < 0x80) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6661 p++;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6662 continue;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6663 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6664
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6665 if (ngx_utf8_decode(&p, n) > 0x10ffff) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6666 /* invalid UTF-8 */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6667 return n;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6668 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6669 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6670
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6671 return len;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6672 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6673 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6674
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6675 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6676
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6677 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6678
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6679
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6680 <section name="Files" id="code_style_files">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6681
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6682 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6683 A typical source file may contain the following sections separated by
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6684 two empty lines:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6685
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6686 <list type="bullet">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6687 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6688 copyright statements
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6689 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6690
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6691 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6692 includes
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6693 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6694
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6695 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6696 preprocessor definitions
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6697 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6698
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6699 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6700 type definitions
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6701 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6702
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6703 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6704 function prototypes
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6705 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6706
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6707 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6708 variable definitions
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6709 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6710
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6711 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6712 function definitions
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6713 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6714
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6715 </list>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6716 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6717
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6718 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6719 Copyright statements look like this:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6720 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6721 /*
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6722 * Copyright (C) Author Name
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6723 * Copyright (C) Organization, Inc.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6724 */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6725 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6726 If the file is modified significantly, the list of authors should be updated,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6727 the new author is added to the top.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6728 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6729
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6730 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6731 The <literal>ngx_config.h</literal> and <literal>ngx_core.h</literal> files
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6732 are always included first, followed by one of
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6733 <literal>ngx_http.h</literal>, <literal>ngx_stream.h</literal>,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6734 or <literal>ngx_mail.h</literal>.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6735 Then follow optional external header files:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6736 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6737 #include <ngx_config.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6738 #include <ngx_core.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6739 #include <ngx_http.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6740
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6741 #include <libxml/parser.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6742 #include <libxml/tree.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6743 #include <libxslt/xslt.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6744
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6745 #if (NGX_HAVE_EXSLT)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6746 #include <libexslt/exslt.h>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6747 #endif
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6748 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6749
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6750 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6751
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6752 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6753 Header files should include the so called "header protection":
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6754 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6755 #ifndef _NGX_PROCESS_CYCLE_H_INCLUDED_
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6756 #define _NGX_PROCESS_CYCLE_H_INCLUDED_
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6757 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6758 #endif /* _NGX_PROCESS_CYCLE_H_INCLUDED_ */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6759 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6760 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6761
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6762 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6763
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6764
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6765 <section name="Comments" id="code_style_comments">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6766 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6767 <list type="bullet">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6768
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6769 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6770 “<literal>//</literal>” comments are not used
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6771 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6772
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6773 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6774 text is written in English, American spelling is preferred
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6775 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6776
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6777 <listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6778 multi-line comments are formatted like this:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6779 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6780 /*
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6781 * The red-black tree code is based on the algorithm described in
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6782 * the "Introduction to Algorithms" by Cormen, Leiserson and Rivest.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6783 */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6784 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6785 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6786 /* find the server configuration for the address:port */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6787 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6788 </listitem>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6789
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6790 </list>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6791 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6792
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6793 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6794
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6795
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6796 <section name="Preprocessor" id="code_style_preprocessor">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6797 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6798 Macro names start from <literal>ngx_</literal> or <literal>NGX_</literal>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6799 (or more specific) prefix.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6800 Macro names for constants are uppercase.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6801 Parameterized macros and macros for initializers are lowercase.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6802 The macro name and value are separated by at least two spaces:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6803 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6804 #define NGX_CONF_BUFFER 4096
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6805
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6806 #define ngx_buf_in_memory(b) (b->temporary \|\| b->memory \|\| b->mmap)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6807
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6808 #define ngx_buf_size(b) \
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6809 (ngx_buf_in_memory(b) ? (off_t) (b->last - b->pos): \
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6810 (b->file_last - b->file_pos))
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6811
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6812 #define ngx_null_string { 0, NULL }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6813 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6814 Conditions are inside parentheses, negation is outside:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6815 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6816 #if (NGX_HAVE_KQUEUE)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6817 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6818 #elif ((NGX_HAVE_DEVPOLL && !(NGX_TEST_BUILD_DEVPOLL)) \
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6819 \|\| (NGX_HAVE_EVENTPORT && !(NGX_TEST_BUILD_EVENTPORT)))
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6820 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6821 #elif (NGX_HAVE_EPOLL && !(NGX_TEST_BUILD_EPOLL))
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6822 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6823 #elif (NGX_HAVE_POLL)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6824 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6825 #else /* select */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6826 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6827 #endif /* NGX_HAVE_KQUEUE */
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6828 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6829 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6830 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6831
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6832
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6833 <section name="Types" id="code_style_types">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6834
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6835 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6836 Type names end with the “<literal>_t</literal>” suffix.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6837 A defined type name is separated by at least two spaces:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6838 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6839 typedef ngx_uint_t ngx_rbtree_key_t;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6840 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6841 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6842
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6843 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6844 Structure types are defined using <literal>typedef</literal>.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6845 Inside structures, member types and names are aligned:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6846 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6847 typedef struct {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6848 size_t len;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6849 u_char *data;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6850 } ngx_str_t;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6851 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6852 Keep alignment identical among different structures in the file.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6853 A structure that points to itself has the name, ending with
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6854 “<literal>_s</literal>”.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6855 Adjacent structure definitions are separated with two empty lines:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6856 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6857 typedef struct ngx_list_part_s ngx_list_part_t;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6858
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6859 struct ngx_list_part_s {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6860 void *elts;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6861 ngx_uint_t nelts;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6862 ngx_list_part_t *next;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6863 };
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6864
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6865
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6866 typedef struct {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6867 ngx_list_part_t *last;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6868 ngx_list_part_t part;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6869 size_t size;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6870 ngx_uint_t nalloc;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6871 ngx_pool_t *pool;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6872 } ngx_list_t;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6873 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6874 Each structure member is declared on its own line:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6875 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6876 typedef struct {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6877 ngx_uint_t hash;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6878 ngx_str_t key;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6879 ngx_str_t value;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6880 u_char *lowcase_key;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6881 } ngx_table_elt_t;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6882 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6883 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6884
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6885 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6886 Function pointers inside structures have defined types ending
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6887 with “<literal>_pt</literal>”:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6888 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6889 typedef ssize_t (ngx_recv_pt)(ngx_connection_t c, u_char *buf, size_t size);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6890 typedef ssize_t (ngx_recv_chain_pt)(ngx_connection_t c, ngx_chain_t *in,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6891 off_t limit);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6892 typedef ssize_t (ngx_send_pt)(ngx_connection_t c, u_char *buf, size_t size);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6893 typedef ngx_chain_t (ngx_send_chain_pt)(ngx_connection_t c, ngx_chain_t in,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6894 off_t limit);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6895
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6896 typedef struct {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6897 ngx_recv_pt recv;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6898 ngx_recv_chain_pt recv_chain;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6899 ngx_recv_pt udp_recv;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6900 ngx_send_pt send;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6901 ngx_send_pt udp_send;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6902 ngx_send_chain_pt udp_send_chain;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6903 ngx_send_chain_pt send_chain;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6904 ngx_uint_t flags;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6905 } ngx_os_io_t;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6906 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6907 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6908
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6909 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6910 Enumerations have types ending with “<literal>_e</literal>”:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6911 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6912 typedef enum {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6913 ngx_http_fastcgi_st_version = 0,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6914 ngx_http_fastcgi_st_type,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6915 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6916 ngx_http_fastcgi_st_padding
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6917 } ngx_http_fastcgi_state_e;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6918 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6919 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6920
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6921 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6922
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6923
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6924 <section name="Variables" id="code_style_variables">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6925
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6926 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6927 Variables are declared sorted by length of a base type, then alphabetically.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6928 Type names and variable names are aligned.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6929 The type and name “columns” are separated with two spaces.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6930 Large arrays are put at the end of a declaration block:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6931 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6932 u_char \| \| rv, p;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6933 ngx_conf_t \| \| *cf;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6934 ngx_uint_t \| \| i, j, k;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6935 unsigned int \| \| len;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6936 struct sockaddr \| \| *sa;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6937 const unsigned char \| \| *data;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6938 ngx_peer_connection_t \| \| *pc;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6939 ngx_http_core_srv_conf_t \| \|**cscfp;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6940 ngx_http_upstream_srv_conf_t\| \| us, uscf;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6941 u_char \| \| text[NGX_SOCKADDR_STRLEN];
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6942 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6943 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6944
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6945 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6946 Static and global variables may be initialized on declaration:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6947 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6948 static ngx_str_t ngx_http_memcached_key = ngx_string("memcached_key");
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6949 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6950
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6951 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6952 static ngx_uint_t mday[] = { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6953 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6954
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6955 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6956 static uint32_t ngx_crc32_table16[] = {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6957 0x00000000, 0x1db71064, 0x3b6e20c8, 0x26d930ac,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6958 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6959 0x9b64c2b0, 0x86d3d2d4, 0xa00ae278, 0xbdbdf21c
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6960 };
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6961 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6962 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6963
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6964 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6965 There is a bunch of commonly used type/name combinations:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6966 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6967 u_char *rv;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6968 ngx_int_t rc;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6969 ngx_conf_t *cf;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6970 ngx_connection_t *c;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6971 ngx_http_request_t *r;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6972 ngx_peer_connection_t *pc;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6973 ngx_http_upstream_srv_conf_t us, uscf;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6974 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6975 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6976 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6977
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6978
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6979 <section name="Functions" id="code_style_functions">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6980
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6981 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6982 All functions (even static ones) should have prototypes.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6983 Prototypes include argument names.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6984 Long prototypes are wrapped with a single indentation on continuation lines:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6985 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6986 static char ngx_http_block(ngx_conf_t cf, ngx_command_t cmd, void conf);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6987 static ngx_int_t ngx_http_init_phases(ngx_conf_t *cf,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6988 ngx_http_core_main_conf_t *cmcf);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6989
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6990 static char ngx_http_merge_servers(ngx_conf_t cf,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6991 ngx_http_core_main_conf_t cmcf, ngx_http_module_t module,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6992 ngx_uint_t ctx_index);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6993 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6994 The function name in a definition starts with a new line.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6995 The function body opening and closing braces are on separate lines.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6996 The body of a function is indented.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6997 There are two empty lines between functions:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6998 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	6999 static ngx_int_t
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7000 ngx_http_find_virtual_server(ngx_http_request_t r, u_char host, size_t len)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7001 {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7002 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7003 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7004
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7005
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7006 static ngx_int_t
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7007 ngx_http_add_addresses(ngx_conf_t cf, ngx_http_core_srv_conf_t cscf,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7008 ngx_http_conf_port_t port, ngx_http_listen_opt_t lsopt)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7009 {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7010 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7011 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7012 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7013 There is no space after the function name and opening parenthesis.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7014 Long function calls are wrapped such that continuation lines start
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7015 from the position of the first function argument.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7016 If this is impossible, format the first continuation line such that it
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7017 ends at position 79:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7018 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7019 ngx_log_debug2(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7020 "http header: \"%V: %V\"",
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7021 &h->key, &h->value);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7022
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7023 hc->busy = ngx_palloc(r->connection->pool,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7024 cscf->large_client_header_buffers.num * sizeof(ngx_buf_t *));
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7025 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7026 The <literal>ngx_inline</literal> macro should be used instead of
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7027 <literal>inline</literal>:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7028 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7029 static ngx_inline void ngx_cpuid(uint32_t i, uint32_t *buf);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7030 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7031 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7032
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7033 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7034
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7035
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7036 <section name="Expressions" id="code_style_expressions">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7037
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7038 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7039 Binary operators except “<literal>.</literal>” and “<literal>−></literal>”
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7040 should be separated from their operands by one space.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7041 Unary operators and subscripts are not separated from their operands by spaces:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7042 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7043 width = width * 10 + (*fmt++ - '0');
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7044 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7045 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7046 ch = (u_char) ((decoded << 4) + (ch - '0'));
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7047 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7048 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7049 r->exten.data = &r->uri.data[i + 1];
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7050 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7051 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7052
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7053 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7054 Type casts are separated by one space from casted expressions.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7055 An asterisk inside type cast is separated with space from type name:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7056 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7057 len = ngx_sock_ntop((struct sockaddr *) sin6, p, len, 1);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7058 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7059 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7060
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7061 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7062 If an expression does not fit into single line, it is wrapped.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7063 The preferred point to break a line is a binary operator.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7064 The continuation line is lined up with the start of expression:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7065 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7066 if (status == NGX_HTTP_MOVED_PERMANENTLY
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7067 \|\| status == NGX_HTTP_MOVED_TEMPORARILY
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7068 \|\| status == NGX_HTTP_SEE_OTHER
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7069 \|\| status == NGX_HTTP_TEMPORARY_REDIRECT
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7070 \|\| status == NGX_HTTP_PERMANENT_REDIRECT)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7071 {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7072 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7073 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7074 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7075 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7076 p->temp_file->warn = "an upstream response is buffered "
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7077 "to a temporary file";
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7078 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7079 As a last resort, it is possible to wrap an expression so that the
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7080 continuation line ends at position 79:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7081 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7082 hinit->hash = ngx_pcalloc(hinit->pool, sizeof(ngx_hash_wildcard_t)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7083 + size * sizeof(ngx_hash_elt_t *));
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7084 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7085 The above rules also apply to sub-expressions,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7086 where each sub-expression has its own indentation level:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7087 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7088 if (((u->conf->cache_use_stale & NGX_HTTP_UPSTREAM_FT_UPDATING)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7089 \|\| c->stale_updating) && !r->background
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7090 && u->conf->cache_background_update)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7091 {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7092 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7093 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7094 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7095 Sometimes, it is convenient to wrap an expression after a cast.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7096 In this case, the continuation line is indented:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7097 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7098 node = (ngx_rbtree_node_t *)
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7099 ((u_char *) lr - offsetof(ngx_rbtree_node_t, color));
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7100 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7101 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7102
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7103 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7104 Pointers are explicitly compared to
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7105 <literal>NULL</literal> (not <literal>0</literal>):
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7106
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7107 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7108 if (ptr != NULL) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7109 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7110 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7111 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7112 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7113
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7114 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7115
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7116
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7117 <section name="Conditionals and Loops" id="code_style_conditionals_and_loops">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7118
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7119 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7120 The “<literal>if</literal>” keyword is separated from the condition by
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7121 one space.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7122 Opening brace is located on the same line, or on a
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7123 dedicated line if the condition takes several lines.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7124 Closing brace is located on a dedicated line, optionally followed
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7125 by “<literal>else if</literal> / <literal>else</literal>”.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7126 Usually, there is an empty line before the
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7127 “<literal>else if</literal> / <literal>else</literal>” part:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7128 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7129 if (node->left == sentinel) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7130 temp = node->right;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7131 subst = node;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7132
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7133 } else if (node->right == sentinel) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7134 temp = node->left;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7135 subst = node;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7136
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7137 } else {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7138 subst = ngx_rbtree_min(node->right, sentinel);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7139
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7140 if (subst->left != sentinel) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7141 temp = subst->left;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7142
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7143 } else {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7144 temp = subst->right;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7145 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7146 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7147 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7148 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7149
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7150 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7151 Similar formatting rules are applied to “<literal>do</literal>”
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7152 and “<literal>while</literal>” loops:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7153 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7154 while (p < last && *p == ' ') {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7155 p++;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7156 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7157 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7158
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7159 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7160 do {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7161 ctx->node = rn;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7162 ctx = ctx->next;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7163 } while (ctx);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7164 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7165 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7166
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7167 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7168 The “<literal>switch</literal>” keyword is separated from the condition by
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7169 one space.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7170 Opening brace is located on the same line.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7171 Closing brace is located on a dedicated line.
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7172 The “<literal>case</literal>” keywords are lined up with
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7173 “<literal>switch</literal>”:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7174 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7175 switch (ch) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7176 case '!':
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7177 looked = 2;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7178 state = ssi_comment0_state;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7179 break;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7180
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7181 case '<':
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7182 copy_end = p;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7183 break;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7184
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7185 default:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7186 copy_end = p;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7187 looked = 0;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7188 state = ssi_start_state;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7189 break;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7190 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7191 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7192 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7193
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7194 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7195 Most “<literal>for</literal>” loops are formatted like this:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7196 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7197 for (i = 0; i < ccf->env.nelts; i++) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7198 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7199 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7200 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7201 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7202 for (q = ngx_queue_head(locations);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7203 q != ngx_queue_sentinel(locations);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7204 q = ngx_queue_next(q))
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7205 {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7206 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7207 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7208 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7209 If some part of the “<literal>for</literal>” statement is omitted,
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7210 this is indicated by the “<literal>/* void */</literal>” comment:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7211 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7212 for (i = 0; /* void */ ; i++) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7213 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7214 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7215 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7216 A loop with an empty body is also indicated by the
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7217 “<literal>/* void */</literal>” comment which may be put on the same line:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7218 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7219 for (cl = busy; cl->next; cl = cl->next) { / void */ }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7220 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7221 An endless loop looks like this:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7222 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7223 for ( ;; ) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7224 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7225 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7226 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7227 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7228
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7229 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7230
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7231
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7232 <section name="Labels" id="code_style_labels">
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7233
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7234 <para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7235 Labels are surrounded with empty lines and are indented at the previous level:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7236 <programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7237 if (i == 0) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7238 u->err = "host not found";
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7239 goto failed;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7240 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7241
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7242 u->addrs = ngx_pcalloc(pool, i * sizeof(ngx_addr_t));
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7243 if (u->addrs == NULL) {
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7244 goto failed;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7245 }
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7246
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7247 u->naddrs = i;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7248
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7249 ...
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7250
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7251 return NGX_OK;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7252
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7253 failed:
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7254
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7255 freeaddrinfo(res);
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7256 return NGX_ERROR;
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7257 </programlisting>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7258 </para>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7259 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7260
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7261 </section>
ccc41545bf55 Extended code style description. Vladimir Homutov <vl@nginx.com> parents: 2151 diff changeset	7262
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	7263 </article>

Mercurial > hg > nginx-site

annotate xml/en/docs/dev/development_guide.xml @ 2277:4ad2cf470ed8