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

annotate xml/en/docs/dev/development_guide.xml @ 1998:18404f5a5600

DevGuide: string initialization macros.

author	Roman Arutyunyan <arut@nginx.com>
date	Wed, 14 Jun 2017 14:13:57 +0300
parents	eeb9cb8f8a54
children	1b086de6a05b

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"
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	12 rev="2">
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>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	378 <literal>ngx_tolower()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	379 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	380
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	381 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	382 <literal>ngx_toupper()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	383 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	384
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	385 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	386 <literal>ngx_strlow()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	387 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	388
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	389 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	390 <literal>ngx_strcasecmp()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	391 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	392
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	393 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	394 <literal>ngx_strncasecmp()</literal>
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>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	456 <literal>ngx_vslprint(buf, last, fmt, args)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	457 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	458
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	459 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	460 <literal>ngx_vsnprint(buf, max, fmt, args)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	461 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	462
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	463 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	464 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	465
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	466 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	467 The full list of formatting options, supported by these functions is
1915 8b7c3b0ef1a4 Semantically marked paths. Vladimir Homutov <vl@nginx.com> parents: 1914 diff changeset	468 in <path>src/core/ngx_string.c</path>. Some of them are:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	469 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	470
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	471
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	472 <list type="bullet">
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	473
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	474 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	475 <literal>%O</literal> — <literal>off_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	476 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	477
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	478 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	479 <literal>%T</literal> — <literal>time_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	480 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	481
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	482 <listitem>
1997 eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	483 <literal>%z</literal> — <literal>ssize_t</literal>
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	484 </listitem>
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	485
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	486 <listitem>
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	487 <literal>%i</literal> — <literal>ngx_int_t</literal>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	488 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	489
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	490 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	491 <literal>%p</literal> — <literal>void *</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	492 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	493
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	494 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	495 <literal>%V</literal> — <literal>ngx_str_t *</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	496 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	497
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	498 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	499 <literal>%s</literal> — <literal>u_char *</literal> (null-terminated)
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	500 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	501
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	502 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	503 <literal>%s</literal> — <literal>size_t + u_char </literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	504 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	505
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	506 </list>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	507
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	508
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	509 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	510 You can prepend <literal>u</literal> on most types to make them unsigned.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	511 To convert output to hex, use <literal>X</literal> or <literal>x</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	512 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	513
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	514 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	515 For example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	516
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	517 <programlisting>
1997 eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	518 u_char buf[NGX_INT_T_LEN];
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	519 size_t len;
eeb9cb8f8a54 DevGuide: fixed type names in the Formatting section. Roman Arutyunyan <arut@nginx.com> parents: 1995 diff changeset	520 ngx_uint_t n;
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	521
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	522 /* set n here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	523
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	524 len = ngx_sprintf(buf, "%ui", n) — buf;
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	525 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	526
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	527 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	528
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	529 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	530
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	531
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	532 <section name="Numeric conversion" id="numeric_conversion">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	533
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	534 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	535 Several functions for numeric conversion are implemented in nginx.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	536 The first four each convert a string of given length to a positive integer of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	537 the indicated type.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	538 They return <literal>NGX_ERROR</literal> on error.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	539
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	540 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	541
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	542 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	543 <literal>ngx_atoi(line, n)</literal> — <literal>ngx_int_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	544 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	545
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	546 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	547 <literal>ngx_atosz(line, n)</literal> — <literal>ssize_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	548 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	549
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	550 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	551 <literal>ngx_atoof(line, n)</literal> — <literal>off_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	552 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	553
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	554 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	555 <literal>ngx_atotm(line, n)</literal> — <literal>time_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	556 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	557
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	558 </list>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	559 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	560
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	561 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	562 There are two additional numeric conversion functions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	563 Like the first four, they return <literal>NGX_ERROR</literal> on error.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	564
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	565 <list type="bullet">
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	566
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	567 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	568 <literal>ngx_atofp(line, n, point)</literal> — Converts a fixed point floating
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	569 number of given length to a positive integer of type
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	570 <literal>ngx_int_t</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	571 The result is shifted left by <literal>point</literal> decimal
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	572 positions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	573 The string representation of the number is expected to have no more
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	574 than <literal>points</literal> fractional digits.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	575 For example, <literal>ngx_atofp("10.5", 4, 2)</literal> returns
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	576 <literal>1050</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	577 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	578
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	579 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	580 <literal>ngx_hextoi(line, n)</literal> — Converts a hexadecimal representation
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	581 of a positive integer to <literal>ngx_int_t</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	582 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	583
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	584 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	585 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	586
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	587 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	588
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	589 <section name="Regular expressions" id="regex">
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	590
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	591 <para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	592 The regular expressions interface in nginx is a wrapper around
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	593 the <link url="http://www.pcre.org">PCRE</link>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	594 library.
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	595 The corresponding header file is <path>src/core/ngx_regex.h</path>.
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	596 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	597
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	598 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	599 To use a regular expression for string matching, it first needs to be
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	600 compiled, which is usually done at the configuration phase.
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	601 Note that since PCRE support is optional, all code using the interface must
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	602 be protected by the surrounding <literal>NGX_PCRE</literal> macro:
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	603
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	604 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	605 #if (NGX_PCRE)
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	606 ngx_regex_t *re;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	607 ngx_regex_compile_t rc;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	608
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	609 u_char errstr[NGX_MAX_CONF_ERRSTR];
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	610
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	611 ngx_str_t value = ngx_string("message (\\d\\d\\d).*Codeword is '(?<cw>\\w+)'");
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	612
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	613 ngx_memzero(&rc, sizeof(ngx_regex_compile_t));
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	614
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	615 rc.pattern = value;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	616 rc.pool = cf->pool;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	617 rc.err.len = NGX_MAX_CONF_ERRSTR;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	618 rc.err.data = errstr;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	619 /* rc.options are passed as is to pcre_compile() */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	620
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	621 if (ngx_regex_compile(&rc) != NGX_OK) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	622 ngx_conf_log_error(NGX_LOG_EMERG, cf, 0, "%V", &rc.err);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	623 return NGX_CONF_ERROR;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	624 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	625
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	626 re = rc.regex;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	627 #endif
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	628 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	629 After successful compilation, the <literal>captures</literal> and
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	630 <literal>named_captures</literal> fields in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	631 <literal>ngx_regex_compile_t</literal> structure contain the count of all
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	632 captures and named captures, respectively, found in the regular expression.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	633 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	634
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	635 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	636 The compiled regular expression can then be used for matching against strings:
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	637 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	638 ngx_int_t n;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	639 int captures[(1 + rc.captures) * 3];
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	640
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	641 ngx_str_t input = ngx_string("This is message 123. Codeword is 'foobar'.");
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	642
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	643 n = ngx_regex_exec(re, &input, captures, (1 + rc.captures) * 3);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	644 if (n >= 0) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	645 /* string matches expression */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	646
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	647 } else if (n == NGX_REGEX_NO_MATCHED) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	648 /* no match was found */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	649
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	650 } else {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	651 /* some error */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	652 ngx_log_error(NGX_LOG_ALERT, log, 0, ngx_regex_exec_n " failed: %i", n);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	653 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	654 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	655 The arguments to <literal>ngx_regex_exec()</literal> are the compiled regular
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	656 expression <literal>re</literal>, the string to match <literal>s</literal>,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	657 an optional array of integers to hold any <literal>captures</literal> that are
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	658 found, and the array's <literal>size</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	659 The size of the <literal>captures</literal> array must be a multiple of three,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	660 as required by the
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	661 <link url="http://www.pcre.org/original/doc/html/pcreapi.html">PCRE API</link>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	662 In the example, the size is calculated from the total number of captures plus
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	663 <literal>1</literal>one for the matched string itself.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	664 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	665
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	666 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	667 If there are matches, captures can be accessed as follows:
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	668 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	669 u_char *p;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	670 size_t size;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	671 ngx_str_t name, value;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	672
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	673 /* all captures */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	674 for (i = 0; i < n * 2; i += 2) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	675 value.data = input.data + captures[i];
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	676 value.len = captures[i + 1] — captures[i];
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	677 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	678
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	679 /* accessing named captures */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	680
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	681 size = rc.name_size;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	682 p = rc.names;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	683
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	684 for (i = 0; i < rc.named_captures; i++, p += size) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	685
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	686 /* capture name */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	687 name.data = &p[2];
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	688 name.len = ngx_strlen(name.data);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	689
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	690 n = 2 * ((p[0] << 8) + p[1]);
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	691
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	692 /* captured value */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	693 value.data = &input.data[captures[n]];
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	694 value.len = captures[n + 1] — captures[n];
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	695 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	696 </programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	697 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	698
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	699 <para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	700 The <literal>ngx_regex_exec_array()</literal> function accepts the array of
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	701 <literal>ngx_regex_elt_t</literal> elements (which are just compiled regular
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	702 expressions with associated names), a string to match, and a log.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	703 The function applies expressions from the array to the string until
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	704 either a match is found or no more expressions are left.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	705 The return value is <literal>NGX_OK</literal> when there is a match and
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	706 <literal>NGX_DECLINED</literal> otherwise, or <literal>NGX_ERROR</literal>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	707 in case of error.
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	708 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	709
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	710 </section>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	711
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	712 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	713
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	714
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	715 <section name="Time" id="time">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	716
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	717 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	718 The <literal>ngx_time_t</literal> structure represents time with three separate
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	719 types for seconds, milliseconds, and the GMT offset:
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	720 <programlisting>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	721 typedef struct {
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	722 time_t sec;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	723 ngx_uint_t msec;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	724 ngx_int_t gmtoff;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	725 } ngx_time_t;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	726 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	727 The <literal>ngx_tm_t</literal> structure is an alias for
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	728 <literal>struct tm</literal> on UNIX platforms and <literal>SYSTEMTIME</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	729 on Windows.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	730 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	731
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	732 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	733 To obtain the current time, it is usually sufficient to access one of the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	734 available global variables, representing the cached time value in the desired
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	735 format.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	736 For example, the <literal>ngx_current_msec</literal> variable holds the number
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	737 of milliseconds elapsed since Epoch and truncated to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	738 <literal>ngx_msec_t</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	739 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	740
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	741 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	742 The available string representations are:
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	743
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	744 <list type="bullet">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	745
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	746 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	747 <literal>ngx_cached_err_log_time</literal> — Used in error log entries:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	748 <literal>"1970/09/28 12:00:00"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	749 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	750
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	751 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	752 <literal>ngx_cached_http_log_time</literal> — Used in HTTP access log entries:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	753 <literal>"28/Sep/1970:12:00:00 +0600"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	754 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	755
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	756 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	757 <literal>ngx_cached_syslog_time</literal> — Used in syslog entries:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	758 <literal>"Sep 28 12:00:00"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	759 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	760
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	761 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	762 <literal>ngx_cached_http_time</literal> — Used in HTTP headers:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	763 <literal>"Mon, 28 Sep 1970 06:00:00 GMT"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	764 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	765
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	766 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	767 <literal>ngx_cached_http_log_iso8601</literal> — The ISO 8601
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	768 standard format:
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	769 <literal>"1970-09-28T12:00:00+06:00"</literal>
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	770 </listitem>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	771
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	772 </list>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	773 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	774
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	775 <para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	776 The <literal>ngx_time()</literal> and <literal>ngx_timeofday()</literal> macros
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	777 return the current time value in seconds and are the preferred way to access
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	778 the cached time value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	779 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	780
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	781 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	782 To obtain the time explicitly, use <literal>ngx_gettimeofday()</literal>,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	783 which updates its argument (pointer to
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	784 <literal>struct timeval</literal>).
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	785 The time is always updated when nginx returns to the event loop from system
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	786 calls.
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	787 To update the time immediately, call <literal>ngx_time_update()</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	788 or <literal>ngx_time_sigsafe_update()</literal> if updating the time in the
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	789 signal handler context.
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	790 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	791
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	792 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	793 The following functions convert <literal>time_t</literal> into the indicated
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	794 broken-down time representation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	795 The first function in each pair converts <literal>time_t</literal> to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	796 <literal>ngx_tm_t</literal> and the second (with the <literal>_libc_</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	797 infix) to <literal>struct tm</literal>:
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	798
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	799 <list type="bullet">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	800
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	801 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	802 <literal>ngx_gmtime(), ngx_libc_gmtime()</literal> — Time expressed as UTC
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	803 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	804
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	805 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	806 <literal>ngx_localtime(), ngx_libc_localtime()</literal> — Time expressed
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	807 relative to the local time zone
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	808 </listitem>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	809
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	810 </list>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	811
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	812 The <literal>ngx_http_time(buf, time)</literal> function returns a string
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	813 representation suitable for use in HTTP headers (for example,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	814 <literal>"Mon, 28 Sep 1970 06:00:00 GMT"</literal>).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	815 The <literal>ngx_http_cookie_time(buf, time)</literal> returns a string
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	816 representation function returns a string representation suitable
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	817 for HTTP cookies (<literal>"Thu, 31-Dec-37 23:55:55 GMT"</literal>).
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	818 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	819
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	820 </section>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	821
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	822
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	823 <section name="Containers" id="containers">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	824
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	825
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	826 <section name="Array" id="array">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	827
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	828 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	829 The nginx array type <literal>ngx_array_t</literal> is defined as follows
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	830 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	831
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	832
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	833 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	834 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	835 void *elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	836 ngx_uint_t nelts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	837 size_t size;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	838 ngx_uint_t nalloc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	839 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	840 } ngx_array_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	841 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	842
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	843 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	844 The elements of the array are available in the <literal>elts</literal> field.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	845 The <literal>nelts</literal> field holds the number of elements.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	846 The <literal>size</literal> field holds the size of a single element and is set
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	847 when the array is initialized.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	848 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	849
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	850 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	851 Use the <literal>ngx_array_create(pool, n, size)</literal> call to create an
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	852 array in a pool, and the <literal>ngx_array_init(array, pool, n, size)</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	853 call to initialize an array object that has already been allocated.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	854 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	855
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	856
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	857 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	858 ngx_array_t *a, b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	859
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	860 /* create an array of strings with preallocated memory for 10 elements */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	861 a = ngx_array_create(pool, 10, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	862
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	863 /* initialize string array for 10 elements */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	864 ngx_array_init(&b, pool, 10, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	865 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	866
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	867 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	868 Use the following functions to add elements to an array:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	869 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	870
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	871 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	872 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	873
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	874 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	875 <literal>ngx_array_push(a)</literal> adds one tail element and returns pointer
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	876 to it
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	877 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	878
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	879 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	880 <literal>ngx_array_push_n(a, n)</literal> adds <literal>n</literal> tail elements
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	881 and returns pointer to the first one
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	882 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	883
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	884 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	885 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	886
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	887 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	888 If the currently allocated amount of memory is not large enough to accommodate
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	889 the new elements, a new block of memory is allocated and the existing elements
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	890 are copied to it.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	891 The new memory block is normally twice as large as the existing one.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	892 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	893
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	894
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	895 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	896 s = ngx_array_push(a);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	897 ss = ngx_array_push_n(&b, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	898 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	899
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	900 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	901
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	902
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	903 <section name="List" id="list">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	904
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	905 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	906 In nginx a list is a sequence of arrays, optimized for inserting a potentially
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	907 large number of items.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	908 The <literal>ngx_list_t</literal> list type is defined as follows:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	909 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	910
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	911
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	912 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	913 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	914 ngx_list_part_t *last;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	915 ngx_list_part_t part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	916 size_t size;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	917 ngx_uint_t nalloc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	918 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	919 } ngx_list_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	920 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	921
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	922 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	923 The actual items are stored in list parts, which are defined as follows:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	924 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	925
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	926
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	927 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	928 typedef struct ngx_list_part_s ngx_list_part_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	929
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	930 struct ngx_list_part_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	931 void *elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	932 ngx_uint_t nelts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	933 ngx_list_part_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	934 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	935 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	936
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	937 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	938 Before use, a list must be initialized by calling
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	939 <literal>ngx_list_init(list, pool, n, size)</literal> or created by calling
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	940 <literal>ngx_list_create(pool, n, size)</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	941 Both functions take as arguments the size of a single item and a number of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	942 items per list part.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	943 To add an item to a list, use the <literal>ngx_list_push(list)</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	944 function.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	945 To iterate over the items, directly access the list fields as shown in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	946 example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	947 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	948
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	949
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	950 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	951 ngx_str_t *v;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	952 ngx_uint_t i;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	953 ngx_list_t *list;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	954 ngx_list_part_t *part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	955
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	956 list = ngx_list_create(pool, 100, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	957 if (list == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	958
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	959 /* add items to the list */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	960
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	961 v = ngx_list_push(list);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	962 if (v == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	963 ngx_str_set(v, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	964
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	965 v = ngx_list_push(list);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	966 if (v == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	967 ngx_str_set(v, "bar");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	968
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	969 /* iterate over the list */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	970
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	971 part = &list->part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	972 v = part->elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	973
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	974 for (i = 0; /* void */; i++) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	975
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	976 if (i >= part->nelts) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	977 if (part->next == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	978 break;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	979 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	980
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	981 part = part->next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	982 v = part->elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	983 i = 0;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	984 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	985
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	986 ngx_do_smth(&v[i]);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	987 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	988 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	989
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	990 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	991 Lists are primarily used for HTTP input and output headers.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	992 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	993
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	994 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	995 Lists do not support item removal.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	996 However, when needed, items can internally be marked as missing without actually
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	997 being removed from the list.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	998 For example, to mark HTTP output headers (which are stored as
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	999 <literal>ngx_table_elt_t</literal> objects) as missing, set the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1000 <literal>hash</literal> field in <literal>ngx_table_elt_t</literal> to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1001 zero.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1002 Items marked in this way are explicitly skipped when the headers are iterated
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1003 over.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1004 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1005
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1006 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1007
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1008
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1009 <section name="Queue" id="queue">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1010
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1011 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1012 In nginx a queue is an intrusive doubly linked list, with each node defined as
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1013 follows:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1014 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1015
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1016
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1017 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1018 typedef struct ngx_queue_s ngx_queue_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1019
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1020 struct ngx_queue_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1021 ngx_queue_t *prev;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1022 ngx_queue_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1023 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1024 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1025
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1026 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1027 The head queue node is not linked with any data.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1028 Use the <literal>ngx_queue_init(q)</literal> call to initialize the list head
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1029 before use.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1030 Queues support the following operations:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1031 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1032
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1033 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1034 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1035
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1036 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1037 <literal>ngx_queue_insert_head(h, x)</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1038 <literal>ngx_queue_insert_tail(h, x)</literal> — Insert a new node
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1039 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1040
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1041 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1042 <literal>ngx_queue_remove(x)</literal> — Remove a queue node
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1043 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1044
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1045 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1046 <literal>ngx_queue_split(h, q, n)</literal> — Split a queue at a node,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1047 returning the queue tail in a separate queue
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1048 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1049
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1050 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1051 <literal>ngx_queue_add(h, n)</literal> — Add a second queue to the first queue
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1052 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1053
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1054 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1055 <literal>ngx_queue_head(h)</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1056 <literal>ngx_queue_last(h)</literal> — Get first or last queue node
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1057 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1058
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1059 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1060 <literal>ngx_queue_sentinel(h)</literal> - Get a queue sentinel object to end
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1061 iteration at
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1062 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1063
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1064 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1065 <literal>ngx_queue_data(q, type, link)</literal> — Get a reference to the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1066 beginning of a queue node data structure, considering the queue field offset in
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1067 it
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1068 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1069
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1070 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1071 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1072
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1073 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1074 An example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1075 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1076
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1077
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1078 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1079 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1080 ngx_str_t value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1081 ngx_queue_t queue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1082 } ngx_foo_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1083
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1084 ngx_foo_t *f;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1085 ngx_queue_t values;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1086
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1087 ngx_queue_init(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1088
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1089 f = ngx_palloc(pool, sizeof(ngx_foo_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1090 if (f == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1091 ngx_str_set(&f->value, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1092
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1093 ngx_queue_insert_tail(&values, f);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1094
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1095 /* insert more nodes here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1096
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1097 for (q = ngx_queue_head(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1098 q != ngx_queue_sentinel(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1099 q = ngx_queue_next(q))
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1100 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1101 f = ngx_queue_data(q, ngx_foo_t, queue);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1102
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1103 ngx_do_smth(&f->value);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1104 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1105 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1106
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1107 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1108
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1109
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1110 <section name="Red-Black tree" id="red_black_tree">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1111
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1112 <para>
1915 8b7c3b0ef1a4 Semantically marked paths. Vladimir Homutov <vl@nginx.com> parents: 1914 diff changeset	1113 The <path>src/core/ngx_rbtree.h</path> header file provides access to the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1114 effective implementation of red-black trees.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1115 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1116
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1117
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1118 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1119 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1120 ngx_rbtree_t rbtree;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1121 ngx_rbtree_node_t sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1122
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1123 /* custom per-tree data here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1124 } my_tree_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1125
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1126 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1127 ngx_rbtree_node_t rbnode;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1128
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1129 /* custom per-node data */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1130 foo_t val;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1131 } my_node_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1132 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1133
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1134 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1135 To deal with a tree as a whole, you need two nodes: root and sentinel.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1136 Typically, they are added to a custom structure, allowing you to
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1137 organize your data into a tree in which the leaves contain a link to or embed
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1138 your data.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1139 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1140
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1141 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1142 To initialize a tree:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1143 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1144
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1145
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1146 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1147 my_tree_t root;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1148
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1149 ngx_rbtree_init(&root.rbtree, &root.sentinel, insert_value_function);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1150 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1151
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1152 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1153 To traverse a tree and insert new values, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1154 "<literal>insert_value</literal>" functions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1155 For example, the <literal>ngx_str_rbtree_insert_value</literal> function deals
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1156 with the <literal>ngx_str_t</literal> type.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1157 Its arguments are pointers to a root node of an insertion, the newly created
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1158 node to be added, and a tree sentinel.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1159 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1160
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1161
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1162 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1163 void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1164 ngx_rbtree_node_t *node,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1165 ngx_rbtree_node_t *sentinel)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1166 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1167
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1168
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1169 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1170 The traversal is pretty straightforward and can be demonstrated with the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1171 following lookup function pattern:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1172 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1173
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1174
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1175 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1176 my_node_t *
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1177 my_rbtree_lookup(ngx_rbtree_t rbtree, foo_t val, uint32_t hash)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1178 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1179 ngx_int_t rc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1180 my_node_t *n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1181 ngx_rbtree_node_t node, sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1182
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1183 node = rbtree->root;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1184 sentinel = rbtree->sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1185
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1186 while (node != sentinel) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1187
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1188 n = (my_node_t *) node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1189
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1190 if (hash != node->key) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1191 node = (hash < node->key) ? node->left : node->right;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1192 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1193 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1194
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1195 rc = compare(val, node->val);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1196
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1197 if (rc < 0) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1198 node = node->left;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1199 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1200 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1201
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1202 if (rc > 0) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1203 node = node->right;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1204 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1205 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1206
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1207 return n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1208 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1209
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1210 return NULL;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1211 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1212 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1213
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1214 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1215 The <literal>compare()</literal> function is a classic comparator function that
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1216 returns a value less than, equal to, or greater than zero.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1217 To speed up lookups and avoid comparing user objects that can be big, an integer
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1218 hash field is used.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1219 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1220
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1221 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1222 To add a node to a tree, allocate a new node, initialize it and call
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1223 <literal>ngx_rbtree_insert()</literal>:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1224 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1225
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1226
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1227 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1228 my_node_t *my_node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1229 ngx_rbtree_node_t *node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1230
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1231 my_node = ngx_palloc(...);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1232 init_custom_data(&my_node->val);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1233
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1234 node = &my_node->rbnode;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1235 node->key = create_key(my_node->val);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1236
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1237 ngx_rbtree_insert(&root->rbtree, node);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1238 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1239
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1240 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1241 To remove a node, call the <literal>ngx_rbtree_delete()</literal> function:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1242 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1243
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1244
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1245 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1246 ngx_rbtree_delete(&root->rbtree, node);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1247 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1248
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1249 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1250
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1251 <section name="Hash" id="hash">
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1252
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1253 <para>
1920 de5251816480 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1919 diff changeset	1254 Hash table functions are declared in <path>src/core/ngx_hash.h</path>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1255 Both exact and wildcard matching are supported.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1256 The latter requires extra setup and is described in a separate section below.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1257 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1258
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1259 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1260 Before initializing a hash, you need to know the number of elements it will
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1261 hold so that nginx can build it optimally.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1262 Two parameters that need to be configured are <literal>max_size</literal>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1263 and <literal>bucket_size</literal>, as detailed in a separate
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1264 <link doc="../hash.xml">document</link>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1265 They are usually configurable by the user.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1266 Hash initialization settings are stored with the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1267 <literal>ngx_hash_init_t</literal> type, and the hash itself is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1268 <literal>ngx_hash_t</literal>:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1269 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1270 ngx_hash_t foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1271 ngx_hash_init_t hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1272
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1273 hash.hash = &foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1274 hash.key = ngx_hash_key;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1275 hash.max_size = 512;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1276 hash.bucket_size = ngx_align(64, ngx_cacheline_size);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1277 hash.name = "foo_hash";
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1278 hash.pool = cf->pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1279 hash.temp_pool = cf->temp_pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1280 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1281 The <literal>key</literal> is a pointer to a function that creates the hash
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1282 integer key from a string.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1283 There are two generic key-creation functions:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1284 <literal>ngx_hash_key(data, len)</literal> and
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1285 <literal>ngx_hash_key_lc(data, len)</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1286 The latter converts a string to all lowercase characters, so the passed string
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1287 must be writeable.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1288 If that is not true, pass the <literal>NGX_HASH_READONLY_KEY</literal> flag
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1289 to the function, initializing the key array (see below).
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1290 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1291
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1292 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1293 The hash keys are stored in <literal>ngx_hash_keys_arrays_t</literal> and
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1294 are initialized with <literal>ngx_hash_keys_array_init(arr, type)</literal>:
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1295 The second parameter (<literal>type</literal>) controls the amount of resources
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1296 preallocated for the hash and can be either <literal>NGX_HASH_SMALL</literal> or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1297 <literal>NGX_HASH_LARGE</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1298 The latter is appropriate if you expect the hash to contain thousands of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1299 elements.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1300
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1301 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1302 ngx_hash_keys_arrays_t foo_keys;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1303
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1304 foo_keys.pool = cf->pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1305 foo_keys.temp_pool = cf->temp_pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1306
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1307 ngx_hash_keys_array_init(&foo_keys, NGX_HASH_SMALL);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1308 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1309 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1310
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1311 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1312 To insert keys into a hash keys array, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1313 <literal>ngx_hash_add_key(keys_array, key, value, flags)</literal> function:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1314 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1315 ngx_str_t k1 = ngx_string("key1");
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1316 ngx_str_t k2 = ngx_string("key2");
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1317
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1318 ngx_hash_add_key(&foo_keys, &k1, &my_data_ptr_1, NGX_HASH_READONLY_KEY);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1319 ngx_hash_add_key(&foo_keys, &k2, &my_data_ptr_2, NGX_HASH_READONLY_KEY);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1320 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1321 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1322
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1323 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1324 To build the hash table, call the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1325 <literal>ngx_hash_init(hinit, key_names, nelts)</literal> function:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1326
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1327 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1328 ngx_hash_init(&hash, foo_keys.keys.elts, foo_keys.keys.nelts);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1329 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1330
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1331 The function fails if <literal>max_size</literal> or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1332 <literal>bucket_size</literal> parameters are not big enough.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1333 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1334
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1335 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1336 When the hash is built, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1337 <literal>ngx_hash_find(hash, key, name, len)</literal> function to look up
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1338 elements:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1339 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1340 my_data_t *data;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1341 ngx_uint_t key;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1342
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1343 key = ngx_hash_key(k1.data, k1.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1344
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1345 data = ngx_hash_find(&foo_hash, key, k1.data, k1.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1346 if (data == NULL) {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1347 /* key not found */
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1348 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1349 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1350
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1351 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1352
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1353 <section name="Wildcard matching" id="wildcard_matching">
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1354
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1355 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1356 To create a hash that works with wildcards, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1357 <literal>ngx_hash_combined_t</literal> type.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1358 It includes the hash type described above and has two additional keys arrays:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1359 <literal>dns_wc_head</literal> and <literal>dns_wc_tail</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1360 The initialization of basic properties is similar to a regular hash:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1361 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1362 ngx_hash_init_t hash
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1363 ngx_hash_combined_t foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1364
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1365 hash.hash = &foo_hash.hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1366 hash.key = ...;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1367 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1368 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1369
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1370 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1371 It is possible to add wildcard keys using the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1372 <literal>NGX_HASH_WILDCARD_KEY</literal> flag:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1373 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1374 /* k1 = ".example.org"; */
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1375 /* k2 = "foo."; /
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1376 ngx_hash_add_key(&foo_keys, &k1, &data1, NGX_HASH_WILDCARD_KEY);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1377 ngx_hash_add_key(&foo_keys, &k2, &data2, NGX_HASH_WILDCARD_KEY);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1378 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1379 The function recognizes wildcards and adds keys into the corresponding arrays.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1380 Please refer to the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1381 <link doc="../http/ngx_http_map_module.xml" id="map"/> module
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1382 documentation for the description of the wildcard syntax and the
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1383 matching algorithm.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1384 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1385
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1386 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1387 Depending on the contents of added keys, you may need to initialize up to three
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1388 key arrays: one for exact matching (described above), and two more to enable
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1389 matching starting from the head or tail of a string:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1390 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1391 if (foo_keys.dns_wc_head.nelts) {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1392
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1393 ngx_qsort(foo_keys.dns_wc_head.elts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1394 (size_t) foo_keys.dns_wc_head.nelts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1395 sizeof(ngx_hash_key_t),
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1396 cmp_dns_wildcards);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1397
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1398 hash.hash = NULL;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1399 hash.temp_pool = pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1400
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1401 if (ngx_hash_wildcard_init(&hash, foo_keys.dns_wc_head.elts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1402 foo_keys.dns_wc_head.nelts)
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1403 != NGX_OK)
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1404 {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1405 return NGX_ERROR;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1406 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1407
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1408 foo_hash.wc_head = (ngx_hash_wildcard_t *) hash.hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1409 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1410 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1411 The keys array needs to be sorted, and initialization results must be added
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1412 to the combined hash.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1413 The initialization of <literal>dns_wc_tail</literal> array is done similarly.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1414 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1415
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1416 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1417 The lookup in a combined hash is handled by the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1418 <literal>ngx_hash_find_combined(chash, key, name, len)</literal>:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1419 <programlisting>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	1420 /* key = "bar.example.org"; — will match ".example.org" */
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	1421 /* key = "foo.example.com"; — will match "foo." /
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1422
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1423 hkey = ngx_hash_key(key.data, key.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1424 res = ngx_hash_find_combined(&foo_hash, hkey, key.data, key.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1425 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1426 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1427
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1428 </section>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1429
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1430 </section>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1431
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1432 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1433
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1434
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1435 <section name="Memory management" id="memory_management">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1436
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1437
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1438 <section name="Heap" id="heap">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1439
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1440 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1441 To allocate memory from system heap, use the following functions:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1442 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1443
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1444 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1445 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1446
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1447 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1448 <literal>ngx_alloc(size, log)</literal> — Allocate memory from system heap.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1449 This is a wrapper around <literal>malloc()</literal> with logging support.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1450 Allocation error and debugging information is logged to <literal>log</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1451 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1452
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1453 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1454 <literal>ngx_calloc(size, log)</literal> — Allocate memory from system heap
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1455 like <literal>ngx_alloc()</literal>, but fill memory with zeros after
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1456 allocation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1457 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1458
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1459 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1460 <literal>ngx_memalign(alignment, size, log)</literal> — Allocate aligned memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1461 from system heap.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1462 This is a wrapper around <literal>posix_memalign()</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1463 on those platforms that provide that function.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1464 Otherwise implementation falls back to <literal>ngx_alloc()</literal> which
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1465 provides maximum alignment.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1466 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1467
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1468 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1469 <literal>ngx_free(p)</literal> — Free allocated memory.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1470 This is a wrapper around <literal>free()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1471 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1472
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1473 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1474 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1475
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1476 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1477
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1478
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1479 <section name="Pool" id="pool">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1480
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1481 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1482 Most nginx allocations are done in pools.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1483 Memory allocated in an nginx pool is freed automatically when the pool is
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1484 destroyed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1485 This provides good allocation performance and makes memory control easy.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1486 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1487
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1488 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1489 A pool internally allocates objects in continuous blocks of memory.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1490 Once a block is full, a new one is allocated and added to the pool memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1491 block list.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1492 When the requested allocation is too large to fit into a block, the request
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1493 is forwarded to the system allocator and the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1494 returned pointer is stored in the pool for further deallocation.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1495 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1496
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1497 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1498 The type for nginx pools is <literal>ngx_pool_t</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1499 The following operations are supported:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1500 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1501
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1502 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1503 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1504
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1505 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1506 <literal>ngx_create_pool(size, log)</literal> — Create a pool with specified
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1507 block size.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1508 The pool object returned is allocated in the pool as well.
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 */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1967 log->action = "sending mp4 to client”;
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1971 closed connection”);
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,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1974 "mp4 start:%ui, length:%ui”, mp4->start, mp4->length);
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1984 sending mp4 to client, client: 127.0.0.1, server: , request: "GET /file.mp4 HTTP/1.1”
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	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.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2582 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	2583 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	2584 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	2585 stores all timeouts currently set.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2586 The key in the tree is of type <literal>ngx_msec_t</literal> and is the time
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2587 when the event expires, expressed in milliseconds since the midnight on of
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2588 January 1, 1970 modulus <literal>ngx_msec_t</literal> max value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2589 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	2590 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	2591 for I/O events and for expiring timeout events.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2592 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2593
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2594 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2595
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2596
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2597 <section name="Posted events" id="posted_events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2598
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2599 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2600 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	2601 point later within the current event loop iteration.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2602 Posting events is a good practice for simplifying code and escaping stack
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2603 overflows.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2604 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	2605 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	2606 <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	2607 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	2608 <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	2609 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	2610 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	2611 events are already handled.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2612 The function <literal>ngx_event_process_posted()</literal> is called to process
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2613 an event queue.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2614 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	2615 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	2616 within the current event loop iteration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2617 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2618
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2619 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2620 An example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2621 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2622
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2623
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2624 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2625 void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2626 ngx_my_connection_read(ngx_connection_t *c)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2627 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2628 ngx_event_t *rev;
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 rev = c->read;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2631
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2632 ngx_add_timer(rev, 1000);
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 rev->handler = ngx_my_read_handler;
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 ngx_my_read(rev);
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
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 void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2641 ngx_my_read_handler(ngx_event_t *rev)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2642 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2643 ssize_t n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2644 ngx_connection_t *c;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2645 u_char buf[256];
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2646
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2647 if (rev->timedout) { /* timeout expired */ }
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 c = rev->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2650
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2651 while (rev->ready) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2652 n = c->recv(c, buf, sizeof(buf));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2653
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2654 if (n == NGX_AGAIN) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2655 break;
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2658 if (n == NGX_ERROR) { /* error */ }
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 /* process buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2661 }
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 if (ngx_handle_read_event(rev, 0) != NGX_OK) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2664 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2665 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2666
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2667 </section>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2670 <section name="Event loop" id="event_loop">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2671
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2672 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2673 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	2674 event loop.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2675 (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	2676 <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	2677 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	2678 <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	2679 repeatedly until the process exits.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2680 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2681
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2682 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2683 The event loop has the following stages:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2684
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2685 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2686
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2687 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2688 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	2689 <literal>ngx_event_find_timer()</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2690 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	2691 number of milliseconds until the node expires.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2692 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2693
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2694 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2695 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	2696 mechanism, chosen by nginx configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2697 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	2698 timeout expires.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2699 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	2700 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	2701 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	2702 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	2703 events.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2704 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2705
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2706 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2707 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	2708 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	2709 unexpired timeout is found.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2710 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	2711 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	2712 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2713
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2714 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2715 Process posted events by calling <literal>ngx_event_process_posted()</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2716 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	2717 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	2718 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2719
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2720 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2721 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2722
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2723 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2724 All nginx processes handle signals as well.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2725 Signal handlers only set global variables which are checked after the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2726 <literal>ngx_process_events_and_timers()</literal> call.
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 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2730
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2731
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2732 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2733
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2734
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2735 <section name="Processes" id="processes">
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2738 There are several types of processes in nginx.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2739 The type of current process is kept in the <literal>ngx_process</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2740 global variable:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2741 </para>
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 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2744
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2745 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2746
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2747 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2748 <literal>NGX_PROCESS_MASTER</literal> — the master process runs the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2749 <literal>ngx_master_process_cycle()</literal> function.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2750 Master process does not have any I/O and responds only to signals.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2751 It reads configuration, creates cycles, starts and controls child processes
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2752 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2753
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2754
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2755 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2756
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2757 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2758
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2759 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2760 <literal>NGX_PROCESS_WORKER</literal> — the worker process runs the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2761 <literal>ngx_worker_process_cycle()</literal> function.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2762 Worker processes are started by master and handle client connections.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2763 They also respond to signals and channel commands, sent from master
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2764 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2765
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2766
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2767 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2768
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2769 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2770
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2771 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2772 <literal>NGX_PROCESS_SINGLE</literal> — single process is the only type
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2773 of processes which exist in the <literal>master_process off</literal> mode.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2774 The cycle function for this process is
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2775 <literal>ngx_single_process_cycle()</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2776 This process creates cycles and handles client connections
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2777 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2778
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2779
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2780 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2781
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2782 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2783
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2784 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2785 <literal>NGX_PROCESS_HELPER</literal> — currently, there are two types of
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2786 helper processes: cache manager and cache loader.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2787 Both of them share the same cycle function
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2788 <literal>ngx_cache_manager_process_cycle()</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2789 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2790
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2791
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2792 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2793
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2794 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2795
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2796 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2797 All nginx processes handle the following signals:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2798 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2799
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2800 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2801
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2802 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2803
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2804 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2805 <literal>NGX_SHUTDOWN_SIGNAL</literal> (<literal>SIGQUIT</literal>) — graceful
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2806 shutdown.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2807 Upon receiving this signal master process sends shutdown signal to all child
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2808 processes.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2809 When no child processes are left, master destroys cycle pool and exits.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2810 A worker process which received this signal, closes all listening sockets and
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2811 waits until timeout tree becomes empty, then destroys cycle pool and exits.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2812 A cache manager process exits right after receiving this signal.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2813 The variable <literal>ngx_quit</literal> is set to one after receiving this
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2814 signal and immediately reset after being processed.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2815 The variable <literal>ngx_exiting</literal> is set to one when worker process
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2816 is in shutdown state
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2817 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2818
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2819
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2820 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2821
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2822 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2823
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2824 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2825 <literal>NGX_TERMINATE_SIGNAL</literal> (<literal>SIGTERM</literal>) -
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2826 terminate.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2827 Upon receiving this signal master process sends terminate signal to all child
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2828 processes.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2829 If child processes do not exit in 1 second, they are killed with the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2830 <literal>SIGKILL</literal> signal.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2831 When no child processes are left, master process destroys cycle pool and exits.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2832 A worker or cache manager process which received this signal destroys cycle
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2833 pool and exits.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2834 The variable <literal>ngx_terminate</literal> is set to one after receiving
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2835 this signal
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2836 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2837
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2838
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2839 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2840
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2841 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2842
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2843 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2844 <literal>NGX_NOACCEPT_SIGNAL</literal> (<literal>SIGWINCH</literal>)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2845 - gracefully shut down worker processes
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2846 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2847
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2848
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2849 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2850
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2851 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2852
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2853 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2854 <literal>NGX_RECONFIGURE_SIGNAL</literal> (<literal>SIGHUP</literal>) -
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2855 reconfigure.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2856 Upon receiving this signal master process creates a new cycle from
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2857 configuration file.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2858 If the new cycle was created successfully, the old cycle is deleted and new
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2859 child processes are started.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2860 Meanwhile, the old processes receive the shutdown signal.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2861 In single-process mode, nginx creates a new cycle as well, but keeps the old
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2862 one until all clients, tied to the old cycle, are gone.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2863 Worker and helper processes ignore this signal
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2864 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2865
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2866
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2867 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2868
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2869 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2870
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2871 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2872 <literal>NGX_REOPEN_SIGNAL</literal> (<literal>SIGUSR1</literal>) — reopen
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2873 files.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2874 Master process passes this signal to workers.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2875 Worker processes reopen all <literal>open_files</literal> from the cycle
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2876 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2877
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2878
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2879 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2880
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2881 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2882
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2883 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2884 <literal>NGX_CHANGEBIN_SIGNAL</literal> (<literal>SIGUSR2</literal>) — change
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2885 nginx binary.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2886 Master process starts a new nginx binary and passes there a list of all listen
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2887 sockets.
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	2888 The list is passed in the environment variable <literal>“NGINX”</literal> in
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2889 text format, where descriptor numbers separated with semicolons.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2890 A new nginx instance reads that variable and adds the sockets to its init
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2891 cycle.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2892 Other processes ignore this signal
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2893 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2894
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2895
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2896 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2897
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2898 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2899
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2900 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2901 While all nginx worker processes are able to receive and properly handle POSIX
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2902 signals, master process normally does not pass any signals to workers and
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2903 helpers with the standard <literal>kill()</literal> syscall.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2904 Instead, nginx uses inter-process channels which allow sending messages between
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2905 all nginx processes.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2906 Currently, however, messages are only sent from master to its children.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2907 Those messages carry the same signals.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2908 The channels are socketpairs with their ends in different processes.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2909 </para>
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 When running nginx binary, several values can be specified next to
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2913 <literal>-s</literal> parameter.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2914 Those values are <literal>stop</literal>, <literal>quit</literal>,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2915 <literal>reopen</literal>, <literal>reload</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2916 They are converted to signals <literal>NGX_TERMINATE_SIGNAL</literal>,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2917 <literal>NGX_SHUTDOWN_SIGNAL</literal>, <literal>NGX_REOPEN_SIGNAL</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2918 and <literal>NGX_RECONFIGURE_SIGNAL</literal> and sent to the nginx master
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2919 process, whose pid is read from nginx pid file.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2920 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2921
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2922 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2923
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2924 <section name="Threads" id="threads">
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2925
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2926 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2927 It is possible to offload tasks that would otherwise block nginx worker process
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2928 into a separate thread.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2929 For example, nginx may be configured to use threads to perform
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2930 <link doc="../http/ngx_http_core_module.xml" id="aio">file I/O</link>.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2931 Another example is using a library that doesn't have asynchronous interface
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2932 and thus cannot be normally used with nginx.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2933 Keep in mind that threads interface is a helper for existing asynchronous
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2934 approach in processing client connections, and by no means a replacement.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2935 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2936
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2937 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2938 To deal with synchronization the following wrappers over pthreads primitives
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2939 are available:
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2940 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2941 typedef pthread_mutex_t ngx_thread_mutex_t;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2942
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2943 ngx_int_t ngx_thread_mutex_create(ngx_thread_mutex_t mtx, ngx_log_t log);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2944 ngx_int_t ngx_thread_mutex_destroy(ngx_thread_mutex_t mtx, ngx_log_t log);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2945 ngx_int_t ngx_thread_mutex_lock(ngx_thread_mutex_t mtx, ngx_log_t log);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2946 ngx_int_t ngx_thread_mutex_unlock(ngx_thread_mutex_t mtx, ngx_log_t log);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2947
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2948 typedef pthread_cond_t ngx_thread_cond_t;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2949
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2950 ngx_int_t ngx_thread_cond_create(ngx_thread_cond_t cond, ngx_log_t log);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2951 ngx_int_t ngx_thread_cond_destroy(ngx_thread_cond_t cond, ngx_log_t log);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2952 ngx_int_t ngx_thread_cond_signal(ngx_thread_cond_t cond, ngx_log_t log);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2953 ngx_int_t ngx_thread_cond_wait(ngx_thread_cond_t cond, ngx_thread_mutex_t mtx,
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2954 ngx_log_t *log);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2955 </programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2956 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2957
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2958 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2959 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	2960 a <link doc="../ngx_core_module.xml" id="thread_pool"/> strategy.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2961 Multiple thread pools may be configured intended for different purposes
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2962 (for example, performing I/O on different sets of disks).
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2963 Each thread pool is created on start and contains a limited number of threads
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2964 that process a queue of tasks.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2965 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	2966 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2967
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2968 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2969 The <literal>src/core/ngx_thread_pool.h</literal> header file contains
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2970 corresponding definitions:
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2971 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2972 struct ngx_thread_task_s {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2973 ngx_thread_task_t *next;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2974 ngx_uint_t id;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2975 void *ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2976 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	2977 ngx_event_t event;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2978 };
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2979
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2980 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	2981
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2982 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	2983 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	2984
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2985 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	2986 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	2987
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2988 </programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2989 At configuration time, a module willing to use threads has to obtain a
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2990 reference to thread pool by calling
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2991 <literal>ngx_thread_pool_add(cf, name)</literal> which will either create a
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2992 new thread pool with given <literal>name</literal> or return a reference
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2993 to an existing one if a pool with such name already exists.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2994 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2995
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2996 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2997 At runtime, the <literal>ngx_thread_task_post(tp, task)</literal> function
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2998 is used to add a <literal>task</literal> into a queue of a thread pool
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2999 <literal>tp</literal>.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3000
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3001 The <literal>ngx_thread_task_t</literal> structure contains all necessary
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3002 to execute user function in thread, pass parameters and setup completion
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3003 handler:
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3004 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3005 typedef struct {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3006 int foo;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3007 } my_thread_ctx_t;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3008
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3009
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3010 static void
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3011 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	3012 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3013 my_thread_ctx_t *ctx = data;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3014
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3015 /* 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	3016 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3017
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3018
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3019 static void
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3020 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	3021 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3022 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	3023
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3024 /* executed in nginx event loop */
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3025 }
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 ngx_int_t
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3029 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	3030 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3031 my_thread_ctx_t *ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3032 ngx_thread_task_t *task;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3033
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3034 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	3035 if (task == NULL) {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3036 return NGX_ERROR;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3037 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3038
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3039 ctx = task->ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3040
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3041 ctx->foo = 42;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3042
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3043 task->handler = my_thread_func;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3044 task->event.handler = my_thread_completion;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3045 task->event.data = ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3046
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3047 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	3048 return NGX_ERROR;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3049 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3050
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3051 return NGX_OK;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3052 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3053 </programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3054
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3055 </para>
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 </section>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3058
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3059
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3060 <section name="Modules" id="Modules">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3061
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3062 <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	3063 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3064 The standalone nginx module resides in a separate directory that contains
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3065 at least two files:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3066 <literal>config</literal> and a file with the module source.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3067 The first file contains all information needed for nginx to integrate
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3068 the module, for example:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3069 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3070 ngx_module_type=CORE
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3071 ngx_module_name=ngx_foo_module
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3072 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	3073
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3074 . auto/module
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3075
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3076 ngx_addon_name=$ngx_module_name
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3077 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3078 The file is a POSIX shell script and it can set (or access) the
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3079 following variables:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3080 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3081
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3082 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3083 <literal>ngx_module_type</literal> — the type of module to build.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3084 Possible options are <literal>CORE</literal>, <literal>HTTP</literal>,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3085 <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	3086 <literal>HTTP_AUX_FILTER</literal>, <literal>MAIL</literal>,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3087 <literal>STREAM</literal>, or <literal>MISC</literal>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3088 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3089
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3090 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3091 <literal>ngx_module_name</literal> — the name of the module.
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3092 A whitespace separated values list is accepted and may be used to build
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3093 multiple modules from a single set of source files.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3094 The first name indicates the name of the output binary for a dynamic module.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3095 The names in this list should match the names used in the module.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3096 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3097
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3098 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3099 <literal>ngx_addon_name</literal> — supplies the name of the module in the
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3100 console output text of the configure script.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3101 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3102
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3103 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3104 <literal>ngx_module_srcs</literal> — a whitespace separated list of source
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3105 files used to compile the module.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3106 The $ngx_addon_dir variable can be used as a placeholder for the path of the
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3107 module source.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3108 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3109
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3110 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3111 <literal>ngx_module_incs</literal> — include paths required to build the module
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3112 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3113
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3114 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3115 <literal>ngx_module_deps</literal> — a list of module's header files.
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3116 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3117
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3118 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3119 <literal>ngx_module_libs</literal> — a list of libraries to link with the
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3120 module.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3121 For example, libpthread would be linked using
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3122 <literal>ngx_module_libs=-lpthread</literal>.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3123 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	3124 nginx:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3125 <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	3126 <literal>PCRE</literal>, <literal>OPENSSL</literal>, <literal>MD5</literal>,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3127 <literal>SHA1</literal>, <literal>ZLIB</literal>, and <literal>PERL</literal>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3128 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3129
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3130 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3131 <literal>ngx_module_link</literal> — set by the build system to
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3132 <literal>DYNAMIC</literal> for a dynamic module or <literal>ADDON</literal>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3133 for a static module and used to perform different actions depending on
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3134 linking type.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3135 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3136
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3137 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3138 <literal>ngx_module_order</literal> — sets the load order for the module which
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3139 is useful for <literal>HTTP_FILTER</literal> and
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3140 <literal>HTTP_AUX_FILTER</literal> module types.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3141 The order is stored in a reverse list.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3142
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3143 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3144 The <literal>ngx_http_copy_filter_module</literal> is near the bottom of the
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3145 list so is one of the first to be executed.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3146 This reads the data for other filters.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3147 Near the top of the list is <literal>ngx_http_write_filter_module</literal>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3148 which writes the data out and is one of the last to be executed.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3149 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3150
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3151 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3152 The format for this option is typically the current module’s name followed by
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3153 a whitespace separated list of modules to insert before, and therefore execute
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3154 after.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3155 The module will be inserted before the last module in the list that is found
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3156 to be currently loaded.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3157 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3158
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3159 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3160 By default for filter modules this is set to
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3161 “<literal>ngx_http_copy_filter</literal>” which will insert the module before
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3162 the copy filter in the list and therefore will execute after the copy filter.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3163 For other module types the default is empty.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3164 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3165
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3166 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3167
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3168 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3169
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3170 A module can be added to nginx by means of the configure script using
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3171 <literal>--add-module=/path/to/module</literal> for static compilation and
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3172 <literal>--add-dynamic-module=/path/to/module</literal> for dynamic compilation.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3173 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3174
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3175 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3176
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3177
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3178 <section name="Core modules" id="core_modules">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3179
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3180 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3181 Modules are building blocks of nginx, and most of its functionality is
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3182 implemented as modules.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3183 The module source file must contain a global variable of
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3184 <literal>ngx_module_t</literal> type which is defined as follows:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3185 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3186 struct ngx_module_s {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3187
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3188 /* private part is omitted */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3189
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3190 void *ctx;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3191 ngx_command_t *commands;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3192 ngx_uint_t type;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3193
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3194 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	3195
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3196 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	3197
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3198 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	3199 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	3200 void (exit_thread)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3201 void (exit_process)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3202
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3203 void (exit_master)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3204
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3205 /* stubs for future extensions are omitted */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3206 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3207 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3208 The omitted private part includes module version, signature and is filled
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3209 using the predefined macro <literal>NGX_MODULE_V1</literal>.
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 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3213 Each module keeps its private data in the <literal>ctx</literal> field,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3214 recognizes specific configuration directives, specified in the
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3215 <literal>commands</literal> array, and may be invoked at certain stages of
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3216 nginx lifecycle.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3217 The module lifecycle consists of the following events:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3218
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3219 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3220
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3221 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3222 Configuration directive handlers are called as they appear
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3223 in configuration files in the context of the master process
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3224 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3225
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3226 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3227 The <literal>init_module</literal> handler is called in the context of
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3228 the master process after the configuration is parsed successfully
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3229 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3230
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3231 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3232 The master process creates worker process(es) and
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3233 <literal>init_process</literal> handler is called in each of them
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3234 </listitem>
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 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3237 When a worker process receives the shutdown command from master, it invokes
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3238 the <literal>exit_process</literal> handler
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3239 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3240
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3241 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3242 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	3243 exiting.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3244 </listitem>
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 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3247
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3248 <note>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3249 <literal>init_module</literal> handler may be called multiple times
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3250 in the master process if the configuration reload is requested.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3251 </note>
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 The <literal>init_master</literal>, <literal>init_thread</literal> and
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3254 <literal>exit_thread</literal> handlers are not implemented at the moment;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3255 Threads in nginx are only used as supplementary I/O facility with its own
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3256 API and <literal>init_master</literal> handler looks unnecessary.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3257 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3258
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3259 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3260 The module <literal>type</literal> defines what exactly is stored in the
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3261 <literal>ctx</literal> field.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3262 There are several types of modules:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3263 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3264 <listitem><literal>NGX_CORE_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3265 <listitem><literal>NGX_EVENT_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3266 <listitem><literal>NGX_HTTP_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3267 <listitem><literal>NGX_MAIL_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3268 <listitem><literal>NGX_STREAM_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3269 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3270 The <literal>NGX_CORE_MODULE</literal> is the most basic and thus the most
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3271 generic and most low-level type of module. Other module types are implemented
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3272 on top of it and provide more convenient way to deal with corresponding
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3273 problem domains, like handling events or http requests.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3274 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3275
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3276 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3277 The examples of core modules are <literal>ngx_core_module</literal>,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3278 <literal>ngx_errlog_module</literal>, <literal>ngx_regex_module</literal>,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3279 <literal>ngx_thread_pool_module</literal>,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3280 <literal>ngx_openssl_module</literal>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3281 modules and, of course, http, stream, mail and event modules itself.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3282 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	3283 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3284 typedef struct {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3285 ngx_str_t name;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3286 void (create_conf)(ngx_cycle_t *cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3287 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	3288 } ngx_core_module_t;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3289 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3290 where the <literal>name</literal> is a string with a module name for
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3291 convenience, <literal>create_conf</literal> and <literal>init_conf</literal>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3292 are pointers to functions that create and initialize module configuration
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3293 correspondingly.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3294 For core modules, nginx will call <literal>create_conf</literal> before parsing
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3295 a new configuration and <literal>init_conf</literal> after all configuration
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3296 was parsed successfully.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3297 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	3298 configuration and sets default values.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3299 The <literal>init_conf</literal> deals with known configuration and thus may
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3300 perform sanity checks and complete initialization.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3301 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3302
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3303 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3304 For example, the simplistic <literal>ngx_foo_module</literal> can look like
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3305 this:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3306 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3307 /*
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3308 * Copyright (C) Author.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3309 */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3310
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3311
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3312 #include <ngx_config.h>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3313 #include <ngx_core.h>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3314
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3315
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3316 typedef struct {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3317 ngx_flag_t enable;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3318 } ngx_foo_conf_t;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3319
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3320
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3321 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	3322 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	3323
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3324 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	3325 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	3326
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3327
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3328 static ngx_command_t ngx_foo_commands[] = {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3329
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3330 { ngx_string("foo_enabled"),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3331 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	3332 ngx_conf_set_flag_slot,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3333 0,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3334 offsetof(ngx_foo_conf_t, enable),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3335 &ngx_foo_enable_post },
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3336
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3337 ngx_null_command
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3338 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3339
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3340
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3341 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	3342 ngx_string("foo"),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3343 ngx_foo_create_conf,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3344 ngx_foo_init_conf
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3345 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3346
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3347
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3348 ngx_module_t ngx_foo_module = {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3349 NGX_MODULE_V1,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3350 &ngx_foo_module_ctx, /* module context */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3351 ngx_foo_commands, /* module directives */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3352 NGX_CORE_MODULE, /* module type */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3353 NULL, /* init master */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3354 NULL, /* init module */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3355 NULL, /* init process */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3356 NULL, /* init thread */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3357 NULL, /* exit thread */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3358 NULL, /* exit process */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3359 NULL, /* exit master */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3360 NGX_MODULE_V1_PADDING
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
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3363
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3364 static void *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3365 ngx_foo_create_conf(ngx_cycle_t *cycle)
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 ngx_foo_conf_t *fcf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3368
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3369 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	3370 if (fcf == NULL) {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3371 return NULL;
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 fcf->enable = NGX_CONF_UNSET;
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 return fcf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3377 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3378
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3379
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3380 static char *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3381 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	3382 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3383 ngx_foo_conf_t *fcf = conf;
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 ngx_conf_init_value(fcf->enable, 0);
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 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3388 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3389
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3390
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3391 static char *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3392 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	3393 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3394 ngx_flag_t *fp = data;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3395
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3396 if (*fp == 0) {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3397 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3398 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3399
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3400 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	3401
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3402 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3403 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3404 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3405 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3406
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3407 </section>
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 <section name="Configuration directives" id="config_directives">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3411
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3412 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3413 The <literal>ngx_command_t</literal> describes single configuration directive.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3414 Each module, supporting configuration, provides an array of such specifications
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3415 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	3416 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3417 struct ngx_command_s {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3418 ngx_str_t name;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3419 ngx_uint_t type;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3420 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	3421 ngx_uint_t conf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3422 ngx_uint_t offset;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3423 void *post;
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 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3426 The array should be terminated by a special value
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3427 “<literal>ngx_null_command</literal>”.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3428 The <literal>name</literal> is the literal name of a directive, as it appears
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3429 in configuration file, for example “<literal>worker_processes</literal>” or
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3430 “<literal>listen</literal>”.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3431 The <literal>type</literal> is a bitfield that controls number of arguments,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3432 command type and other properties using corresponding flags.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3433 Arguments flags:
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 <list type="bullet">
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 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3438 <literal>NGX_CONF_NOARGS</literal> — directive without arguments
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3439 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3440
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3441 <listitem><literal>NGX_CONF_1MORE</literal> — one required argument</listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3442
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3443 <listitem><literal>NGX_CONF_2MORE</literal> — two required arguments</listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3444
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3445 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3446 <literal>NGX_CONF_TAKE1..7</literal> — exactly 1..7 arguments
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3447 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3448
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3449 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3450 <literal>NGX_CONF_TAKE12, 13, 23, 123, 1234</literal> — one or two arguments,
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3451 or other combinations
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3452 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3453
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3454 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3455
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3456 Directive types:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3457
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3458 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3459
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3460 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3461 <literal>NGX_CONF_BLOCK</literal> — the directive is a block, i.e. it may
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3462 contain other directives in curly braces, or even implement its own parser
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3463 to handle contents inside.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3464 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3465
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3466 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3467 <literal>NGX_CONF_FLAG</literal> — the directive value is a flag, a boolean
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3468 value represented by “<literal>on</literal>” or “<literal>off</literal>”
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3469 strings.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3470 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3471 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3472
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3473 Context of a directive defines where in the configuration it may appear
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3474 and how to access module context to store corresponding values:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3475 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3476
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3477 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3478 <literal>NGX_MAIN_CONF</literal> — top level configuration
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3479 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3480
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3481 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3482 <literal>NGX_HTTP_MAIN_CONF</literal> — in the http block
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3483 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3484
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3485 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3486 <literal>NGX_HTTP_SRV_CONF</literal> — in the http server block
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3487 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3488
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3489 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3490 <literal>NGX_HTTP_LOC_CONF</literal> — in the http location
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3491 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3492
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3493 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3494 <literal>NGX_HTTP_UPS_CONF</literal> — in the http upstream block
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3495 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3496
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3497 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3498 <literal>NGX_HTTP_SIF_CONF</literal> — in the http server “if”
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3499 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3500
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3501 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3502 <literal>NGX_HTTP_LIF_CONF</literal> — in the http location “if”
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3503 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3504
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3505 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3506 <literal>NGX_HTTP_LMT_CONF</literal> — in the http “limit_except”
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3507 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3508
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3509 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3510 <literal>NGX_STREAM_MAIN_CONF</literal> — in the stream block
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3511 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3512
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3513 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3514 <literal>NGX_STREAM_SRV_CONF</literal> — in the stream server block
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3515 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3516
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3517 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3518 <literal>NGX_STREAM_UPS_CONF</literal> — in the stream upstream block
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3519 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3520
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3521 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3522 <literal>NGX_MAIL_MAIN_CONF</literal> — in the the mail block
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3523 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3524
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3525 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3526 <literal>NGX_MAIL_SRV_CONF</literal> — in the mail server block
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3527 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3528
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3529 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3530 <literal>NGX_EVENT_CONF</literal> — in the event block
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3531 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3532
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3533 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3534 <literal>NGX_DIRECT_CONF</literal> — used by modules that don't
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3535 create a hierarchy of contexts and store module configuration directly in ctx
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3536 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3537 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3538 The configuration parser uses this flags to throw an error in case of
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3539 a misplaced directive and calls directive handlers supplied with a proper
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3540 configuration pointer, so that same directives in different locations could
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3541 store their values in distinct places.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3542 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3543
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3544 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3545 The <literal>set</literal> field defines a handler that processes a directive
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3546 and stores parsed values into corresponding configuration.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3547 Nginx offers a convenient set of functions that perform common conversions:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3548
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3549 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3550
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3551 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3552 <literal>ngx_conf_set_flag_slot</literal> — converts literal
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3553 “<literal>on</literal>” or “<literal>off</literal>” strings into
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3554 <literal>ngx_flag_t</literal> type with values 1 or 0
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3555 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3556
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3557 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3558 <literal>ngx_conf_set_str_slot</literal> — stores string as a value of the
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3559 <literal>ngx_str_t</literal> type
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3560 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3561
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3562 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3563 <literal>ngx_conf_set_str_array_slot</literal> — appends
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3564 <literal>ngx_array_t</literal> of <literal>ngx_str_t</literal> with a new value.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3565 The array is created if not yet exists
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3566 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3567
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3568 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3569 <literal>ngx_conf_set_keyval_slot</literal> — appends
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3570 <literal>ngx_array_t</literal> of <literal>ngx_keyval_t</literal> with
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3571 a new value, where key is the first string and value is second.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3572 The array is created if not yet exists
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3573 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3574
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3575 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3576 <literal>ngx_conf_set_num_slot</literal> — converts directive argument
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3577 to a <literal>ngx_int_t</literal> value
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3578 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3579
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3580 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3581 <literal>ngx_conf_set_size_slot</literal> — converts
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3582 <link doc="../syntax.xml">size</link> to <literal>size_t</literal> value
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3583 in bytes
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3584 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3585
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3586 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3587 <literal>ngx_conf_set_off_slot</literal> — converts
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3588 <link doc="../syntax.xml">offset</link> to <literal>off_t</literal> value
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3589 in bytes
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3590 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3591
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3592 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3593 <literal>ngx_conf_set_msec_slot</literal> — converts
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3594 <link doc="../syntax.xml">time</link> to <literal>ngx_msec_t</literal> value
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3595 in milliseconds
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3596 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3597
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3598 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3599 <literal>ngx_conf_set_sec_slot</literal> — converts
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3600 <link doc="../syntax.xml">time</link> to <literal>time_t</literal> value
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3601 in seconds
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3602 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3603
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3604 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3605 <literal>ngx_conf_set_bufs_slot</literal> — converts two arguments
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3606 into <literal>ngx_bufs_t</literal> that holds <literal>ngx_int_t</literal>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3607 number and <link doc="../syntax.xml">size</link> of buffers
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3608 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3609
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3610 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3611 <literal>ngx_conf_set_enum_slot</literal> — converts argument
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3612 into <literal>ngx_uint_t</literal> value.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3613 The null-terminated array of <literal>ngx_conf_enum_t</literal> passed in the
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3614 <literal>post</literal> field defines acceptable strings and corresponding
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3615 integer values
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3616 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3617
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3618 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3619 <literal>ngx_conf_set_bitmask_slot</literal> — arguments are converted to
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3620 <literal>ngx_uint_t</literal> value and OR'ed with the resulting value,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3621 forming a bitmask.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3622 The null-terminated array of <literal>ngx_conf_bitmask_t</literal> passed in
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3623 the <literal>post</literal> field defines acceptable strings and corresponding
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3624 mask values
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3625 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3626
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3627 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3628 <literal>set_path_slot</literal> — converts arguments to
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3629 <literal>ngx_path_t</literal> type and performs all required initializations.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3630 See the
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3631 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_temp_path">proxy_temp_path</link>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3632 directive description for details
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3633 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3634
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3635 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3636 <literal>set_access_slot</literal> — converts arguments to file permissions
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3637 mask.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3638 See the
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3639 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_store_access">proxy_store_access</link>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3640 directive description for details
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3641 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3642
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3643 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3644
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3645 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3646
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3647 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3648 The <literal>conf</literal> field defines which context is used to store
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3649 the value of the directive, or zero if contexts are not used.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3650 Only simple core modules use configuration without context and set
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3651 <literal>NGX_DIRECT_CONF</literal> flag.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3652 In real life, such modules like http or stream require more sophisticated
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3653 configuration that can be applied per-server or per-location, or even more
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3654 precisely, in the context of the “<literal>if</literal>” directive or
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3655 some limit.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3656 In this modules, configuration structure is more complex.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3657 Please refer to corresponding modules description to understand how
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3658 they manage their configuration.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3659
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3660 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3661 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3662 <literal>NGX_HTTP_MAIN_CONF_OFFSET</literal> — http block configuration
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3663 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3664
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3665 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3666 <literal>NGX_HTTP_SRV_CONF_OFFSET</literal> — http server configuration
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3667 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3668
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3669 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3670 <literal>NGX_HTTP_LOC_CONF_OFFSET</literal> — http location configuration
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3671 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3672
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3673 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3674 <literal>NGX_STREAM_MAIN_CONF_OFFSET</literal> — stream block configuration
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3675 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3676
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3677 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3678 <literal>NGX_STREAM_SRV_CONF_OFFSET</literal> — stream server configuration
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3679 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3680
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3681 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3682 <literal>NGX_MAIL_MAIN_CONF_OFFSET</literal> — mail block configuration
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3683 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3684
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3685 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3686 <literal>NGX_MAIL_SRV_CONF_OFFSET</literal> — mail server configuration
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3687 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3688
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3689 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3690
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3691 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3692
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3693 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3694 The <literal>offset</literal> defines an offset of a field in a module
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3695 configuration structure that holds values of this particular directive.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3696 The typical use is to employ <literal>offsetof()</literal> macro.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3697 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3698
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3699 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3700 The <literal>post</literal> is a twofold field: it may be used to define
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3701 a handler to be called after main handler completed or to pass additional
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3702 data to the main handler.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3703 In the first case, <literal>ngx_conf_post_t</literal> structure needs to
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3704 be initialized with a pointer to handler, for example:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3705 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3706 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	3707 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	3708 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3709 The <literal>post</literal> argument is the <literal>ngx_conf_post_t</literal>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3710 object itself, and the <literal>data</literal> is a pointer to value,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3711 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	3712 </para>
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 </section>
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 </section>
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
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3719 <section name="HTTP" id="http">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3720
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3721
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3722 <section name="Connection" id="http_connection">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3723
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3724 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3725 Each client HTTP connection runs through the following stages:
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3726 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3727
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3728 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3729
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3730 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3731 <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	3732 This handler is called in response to a read notification on a listen socket.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3733 A new <literal>ngx_connecton_t</literal> object is created at this stage.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3734 The object wraps the newly accepted client socket.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3735 Each nginx listener provides a handler to pass the new connection object to.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3736 For HTTP connections it's <literal>ngx_http_init_connection(c)</literal>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3737 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3738
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3739 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3740 <literal>ngx_http_init_connection()</literal> performs early initialization of
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3741 an HTTP connection.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3742 At this stage an <literal>ngx_http_connection_t</literal> object is created for
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3743 the connection and its reference is stored in connection's
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3744 <literal>data</literal> field.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3745 Later it will be substituted with an HTTP request object.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3746 PROXY protocol parser and SSL handshake are started at this stage as well
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3747 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3748
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3749 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3750 <literal>ngx_http_wait_request_handler()</literal> is a read event handler, that
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3751 is called when data is available in the client socket.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3752 At this stage an HTTP request object <literal>ngx_http_request_t</literal> is
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3753 created and set to connection's <literal>data</literal> field
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3754 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3755
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3756 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3757 <literal>ngx_http_process_request_line()</literal> is a read event handler,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3758 which reads client request line.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3759 The handler is set by <literal>ngx_http_wait_request_handler()</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3760 Reading is done into connection's <literal>buffer</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3761 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	3762 <link doc="../http/ngx_http_core_module.xml" id="client_header_buffer_size"/>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3763 The entire client header is supposed to fit the buffer.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3764 If the initial size is not enough, a bigger buffer is allocated, whose size is
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3765 set by the <literal>large_client_header_buffers</literal> directive
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3766 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3767
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3768 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3769 <literal>ngx_http_process_request_headers()</literal> is a read event handler,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3770 which is set after <literal>ngx_http_process_request_line()</literal> to read
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3771 client request header
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3772 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3773
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3774 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3775 <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	3776 is completely read and parsed.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3777 This function runs request phases from
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3778 <literal>NGX_HTTP_POST_READ_PHASE</literal> to
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3779 <literal>NGX_HTTP_CONTENT_PHASE</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3780 The last phase is supposed to generate response and pass it along the filter
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3781 chain.
1979 ff28ca78bef3 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1976 diff changeset	3782 The response is not necessarily sent to the client at this phase.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3783 It may remain buffered and will be sent at the finalization stage
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3784 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3785
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3786 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3787 <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	3788 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	3789 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	3790 response.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3791 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	3792 HTTP writer <literal>ngx_http_writer()</literal> is activated to finish
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3793 sending outstanding data
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3794 </listitem>
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 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3797 <literal>ngx_http_finalize_connection()</literal> is called when the response is
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3798 completely sent to the client and the request can be destroyed.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3799 If client connection keepalive feature is enabled,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3800 <literal>ngx_http_set_keepalive()</literal> is called, which destroys current
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3801 request and waits for the next request on the connection.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3802 Otherwise, <literal>ngx_http_close_request()</literal> destroys both the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3803 request and the connection
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3806 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3807
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3808 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3809
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3810
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3811 <section name="Request" id="http_request">
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 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3814 For each client HTTP request the <literal>ngx_http_request_t</literal> object is
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3815 created. Some of the fields of this object:
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3816 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3817
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3818 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3819
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3820 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3821
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3822 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3823 <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	3824 client connection object.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3825 Several requests may reference the same connection object at the same time -
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3826 one main request and its subrequests.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3827 After a request is deleted, a new request may be created on the same connection.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3828 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3829
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3830 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3831 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	3832 <literal>data</literal> field points back to the request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3833 Such request is called active, as opposed to the other requests tied with the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3834 connection.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3835 Active request is used to handle client connection events and is allowed to
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3836 output its response to the client.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3837 Normally, each request becomes active at some point to be able to send its
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3838 output
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3839 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3840
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3841 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3842
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3843 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3844
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3845 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3846 <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	3847 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	3848 (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	3849 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	3850 <literal>ctx_index</literal> position.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3851 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	3852 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3853
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3854 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3855
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3856 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3857 <literal>ngx_http_get_module_ctx(r, module)</literal> — returns
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3858 <literal>module</literal>'s context
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3859 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3860
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3861 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3862 <literal>ngx_http_set_ctx(r, c, module)</literal> — sets <literal>c</literal>
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3863 as <literal>module</literal>'s context
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3864 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3865
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3866 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3867
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3868 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3869
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3870 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3871 <literal>main_conf, srv_conf, loc_conf</literal> — arrays of current request
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3872 configurations.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3873 Configurations are stored at module's <literal>ctx_index</literal> positions
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3874 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3875
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3876 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3877 <literal>read_event_handler</literal>, <literal>write_event_handler</literal> -
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3878 read and write event handlers for the request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3879 Normally, an HTTP connection has <literal>ngx_http_request_handler()</literal>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3880 set as both read and write event handlers.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3881 This function calls <literal>read_event_handler</literal> and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3882 <literal>write_event_handler</literal> handlers of the currently active request
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3883 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3884
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3885 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3886 <literal>cache</literal> — request cache object for caching upstream response
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3887 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3888
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3889 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3890 <literal>upstream</literal> — request upstream object for proxying
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3891 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3892
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3893 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3894 <literal>pool</literal> — request pool.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3895 This pool is destroyed when the request is deleted.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3896 The request object itself is allocated in this pool.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3897 For allocations which should be available throughout the client connection's
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3898 lifetime, <literal>ngx_connection_t</literal>'s pool should be used instead
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3899 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3900
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3901 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3902 <literal>header_in</literal> — buffer where client HTTP request header in read
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3903 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3904
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3905 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3906 <literal>headers_in, headers_out</literal> — input and output HTTP headers
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3907 objects.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3908 Both objects contain the <literal>headers</literal> field of type
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3909 <literal>ngx_list_t</literal> keeping the raw list of headers.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3910 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	3911 separate fields, for example <literal>content_length_n</literal>,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3912 <literal>status</literal> etc
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3913 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3914
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3915 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3916 <literal>request_body</literal> — client request body object
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3917 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3918
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3919 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3920 <literal>start_sec, start_msec</literal> — time point when the request was
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3921 created.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3922 Used for tracking request duration
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3923 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3924
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3925 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3926 <literal>method, method_name</literal> — numeric and textual representation of
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3927 client HTTP request method.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3928 Numeric values for methods are defined in
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3929 <literal>src/http/ngx_http_request.h</literal> with macros
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3930 <literal>NGX_HTTP_GET, NGX_HTTP_HEAD, NGX_HTTP_POST</literal> etc
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3931 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3932
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3933 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3934 <literal>http_protocol, http_version, http_major, http_minor</literal> -
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	3935 client HTTP protocol version in its original textual form (“HTTP/1.0”,
8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	3936 “HTTP/1.1” etc), numeric form (<literal>NGX_HTTP_VERSION_10</literal>,
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3937 <literal>NGX_HTTP_VERSION_11</literal> etc) and separate major and minor
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3938 versions
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3939 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3940
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3941 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3942 <literal>request_line, unparsed_uri</literal> — client original request line
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3943 and URI
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>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3947 <literal>uri, args, exten</literal> — current request URI, arguments and file
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3948 extention.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3949 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	3950 normalization.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3951 Throughout request processing, these value can change while performing internal
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3952 redirects
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3953 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3954
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3955 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3956 <literal>main</literal> — pointer to a main request object.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3957 This object is created to process client HTTP request, as opposed to
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3958 subrequests, created to perform a specific sub-task within the main request
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3959 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3960
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3961 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3962 <literal>parent</literal> — pointer to a parent request of a subrequest
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3963 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3964
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3965 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3966 <literal>postponed</literal> — list of output buffers and subrequests in the
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3967 order they are sent and created.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3968 The list is used by the postpone filter to provide consistent request output,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3969 when parts of it are created by subrequests
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3970 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3971
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3972 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3973 <literal>post_subrequest</literal> — pointer to a handler with context to be
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3974 called when a subrequest gets finalized.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3975 Unused for main requests
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3976 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3977
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3978 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3979
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3980 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3981 <literal>posted_requests</literal> — list of requests to be started or
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3982 resumed.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3983 Starting or resuming is done by calling the request's
1932 937e03180281 Fixed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1929 diff changeset	3984 <literal>write_event_handler</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3985 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	3986 request phases and then produces the output.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3987 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3988
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3989 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3990 A request is usually posted by the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3991 <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	3992 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	3993 The function <literal>ngx_http_run_posted_requests(c)</literal> runs all
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3994 requests, posted in the main request of the passed connection's active request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3995 This function should be called in all event handlers, which can lead to new
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3996 posted requests.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3997 Normally, it's called always after invoking a request's read or write handler
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3998 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3999
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4000 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4001
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4002 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4003 <literal>phase_handler</literal> — index of current request phase
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4004 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4005
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4006 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4007 <literal>ncaptures, captures, captures_data</literal> — regex captures produced
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4008 by the last regex match of the request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4009 While processing a request, there's a number of places where a regex match can
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4010 happen: map lookup, server lookup by SNI or HTTP Host, rewrite, proxy_redirect
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4011 etc.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4012 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	4013 The field <literal>ncaptures</literal> holds the number of captures,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4014 <literal>captures</literal> holds captures boundaries,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4015 <literal>captures_data</literal> holds a string, against which the regex was
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4016 matched and which should be used to extract captures.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4017 After each new regex match request captures are reset to hold new values
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4018 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4019
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4020 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4021 <literal>count</literal> — request reference counter.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4022 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	4023 Increasing the counter is done by simple <literal>r->main->count++</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4024 To decrease the counter <literal>ngx_http_finalize_request(r, rc)</literal>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4025 should be called.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4026 Creation of a subrequest or running request body read process increase the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4027 counter
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4028 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4029
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4030 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4031 <literal>subrequests</literal> — current subrequest nesting level.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4032 Each subrequest gets the nesting level of its parent decreased by one.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4033 Once the value reaches zero an error is generated.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4034 The value for the main request is defined by the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4035 <literal>NGX_HTTP_MAX_SUBREQUESTS</literal> constant
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4036 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4037
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4038 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4039 <literal>uri_changes</literal> — number of URI changes left for the request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4040 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	4041 <literal>NGX_HTTP_MAX_URI_CHANGES</literal> constant.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4042 With each change the value is decreased until it reaches zero.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4043 In the latter case an error is generated.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4044 The actions considered as URI changes are rewrites and internal redirects to
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4045 normal or named locations
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4046 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4047
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4048 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4049 <literal>blocked</literal> — counter of blocks held on the request.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4050 While this value is non-zero, request cannot be terminated.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4051 Currently, this value is increased by pending AIO operations (POSIX AIO and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4052 thread operations) and active cache lock
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4053 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4054
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4055 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4056 <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	4057 output produced by the request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4058 A number of filters can buffer output, for example sub_filter can buffer data
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4059 due to a partial string match, copy filter can buffer data because of the lack
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4060 of free output_buffers etc.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4061 As long as this value is non-zero, request is not finalized, expecting the flush
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4062 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4063
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4064 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4065 <literal>header_only</literal> — flag showing that output does not require body.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4066 For example, this flag is used by HTTP HEAD requests
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4067 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4068
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4069 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4070 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4071 <literal>keepalive</literal> — flag showing if client connection keepalive is
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4072 supported.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4073 The value is inferred from HTTP version and <header>Connection</header> header
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4074 value
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4075 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4076 </listitem>
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 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4079 <literal>header_sent</literal> — flag showing that output header has already
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4080 been sent by the request
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4081 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4082
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4083 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4084 <literal>internal</literal> — flag showing that current request is internal.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4085 To enter the internal state, a request should pass through an internal
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4086 redirect or be a subrequest.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4087 Internal requests are allowed to enter internal locations
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4088 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4089
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4090 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4091 <literal>allow_ranges</literal> — flag showing that partial response can be
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4092 sent to client, if requested by the HTTP Range header
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4093 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4094
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4095 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4096 <literal>subrequest_ranges</literal> — flag showing that a partial response is
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4097 allowed to be sent while processing a subrequest
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4098 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4099
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4100 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4101 <literal>single_range</literal> — flag showing that only a single continuous
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4102 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	4103 This flag is usually set when sending a stream of data, for example from a
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4104 proxied server, and the entire response is not available at once
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4105 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4106
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4107 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4108 <literal>main_filter_need_in_memory, filter_need_in_memory</literal> — flags
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4109 showing that the output should be produced in memory buffers but not in files.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4110 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	4111 sendfile is enabled.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4112 The difference between these two flags is the location of filter modules which
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4113 set them.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4114 Filters called before the postpone filter in filter chain, set
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4115 <literal>filter_need_in_memory</literal> requesting that only the current
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4116 request output should come in memory buffers.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4117 Filters called later in filter chain set
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4118 <literal>main_filter_need_in_memory</literal> requiring that both the main
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4119 request and all the subrequest read files in memory while sending output
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4120 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4121
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4122 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4123 <literal>filter_need_temporary</literal> — flag showing that the request output
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4124 should be produced in temporary buffers, but not in readonly memory buffers or
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4125 file buffers.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4126 This is used by filters which may change output directly in the buffers, where
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4127 it's sent </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4128
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4129 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4130
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4131 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4132
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4133
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4134 <section name="Configuration" id="http_conf">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4135
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4136 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4137 Each HTTP module may have three types of configuration:
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4138 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4139
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4140 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4141
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4142 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4143 Main configuration.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4144 This configuration applies to the entire nginx http{} block. This is global
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4145 configuration.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4146 It stores global settings for a module
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4147 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4148
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4149 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4150 Server configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	4151 This configuration applies to a single nginx server{}.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4152 It stores server-specific settings for a module
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4153 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4154
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4155 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4156 Location configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	4157 This configuration applies to a single location{}, if{} or limit_except() block.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4158 This configuration stores settings specific to a location
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4159 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4160
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4161 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4162
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4163 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4164 Configuration structures are created at nginx configuration stage by calling
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4165 functions, which allocate these structures, initialize them and merge.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4166 The following example shows how to create a simple module location
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4167 configuration.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4168 The configuration has one setting <literal>foo</literal> of unsiged integer
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4169 type.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4170 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4171
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4172 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4173 typedef struct {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4174 ngx_uint_t foo;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4175 } ngx_http_foo_loc_conf_t;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4176
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4177
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4178 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	4179 NULL, /* preconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4180 NULL, /* postconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4181
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4182 NULL, /* create main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4183 NULL, /* init main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4184
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4185 NULL, /* create server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4186 NULL, /* merge server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4187
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4188 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	4189 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	4190 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4191
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4192
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4193 static void *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4194 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	4195 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4196 ngx_http_foo_loc_conf_t *conf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4197
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4198 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	4199 if (conf == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4200 return NULL;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4201 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4202
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4203 conf->foo = NGX_CONF_UNSET_UINT;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4204
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4205 return conf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4206 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4207
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4208
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4209 static char *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4210 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	4211 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4212 ngx_http_foo_loc_conf_t *prev = parent;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4213 ngx_http_foo_loc_conf_t *conf = child;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4214
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4215 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	4216 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4217 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4218
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4219 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4220 As seen in the example, <literal>ngx_http_foo_create_loc_conf()</literal>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4221 function creates a new configuration structure and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4222 <literal>ngx_http_foo_merge_loc_conf()</literal> merges a configuration with
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4223 another configuration from a higher level.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4224 In fact, server and location configuration do not only exist at server and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4225 location levels, but also created for all the levels above.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4226 Specifically, a server configuration is created at the main level as well and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4227 location configurations are created for main, server and location levels.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4228 These configurations make it possible to specify server and location-specific
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4229 settings at any level of nginx configuration file.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4230 Eventually configurations are merged down.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4231 To indicate a missing setting and ignore it while merging, nginx provides a
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4232 number of macros like <literal>NGX_CONF_UNSET</literal> and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4233 <literal>NGX_CONF_UNSET_UINT</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4234 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	4235 <literal>ngx_conf_merge_uint_value()</literal> provide a convenient way to
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4236 merge a setting and set the default value if none of configurations provided an
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4237 explicit value.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4238 For complete list of macros for different types see
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4239 <literal>src/core/ngx_conf_file.h</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4240 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4241
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4242 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4243 To access configuration of any HTTP module at configuration time, the following
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4244 macros are available.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4245 They receive <literal>ngx_conf_t</literal> reference as the first argument.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4246 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4247
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4248 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4249
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4250 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4251 <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	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 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4255 <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	4256 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4257
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4258 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4259 <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	4260 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4261
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4262 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4263
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 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	4266 standard nginx core module
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4267 <link doc="../http/ngx_http_core_module.xml">ngx_http_core_module</link>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4268 and changes
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4269 location content handler kept in the <literal>handler</literal> field of the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4270 structure.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4271 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4272
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4273 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4274 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	4275
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4276
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4277 static ngx_command_t ngx_http_foo_commands[] = {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4278
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4279 { ngx_string("foo"),
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4280 NGX_HTTP_LOC_CONF\|NGX_CONF_NOARGS,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4281 ngx_http_foo,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4282 0,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4283 0,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4284 NULL },
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 ngx_null_command
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4287 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4288
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4289
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4290 static char *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4291 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	4292 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4293 ngx_http_core_loc_conf_t *clcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4294
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4295 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	4296 clcf->handler = ngx_http_bar_handler;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4297
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4298 return NGX_CONF_OK;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4299 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4300 </programlisting>
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 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4303 In runtime the following macros are available to get configurations of HTTP
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4304 modules.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4305 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4306
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4307 <list type="bullet">
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 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4310 <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	4311 </listitem>
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 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4314 <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	4315 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4316
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4317 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4318 <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	4319 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4320
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4321 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4322
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4323 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4324 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	4325 <literal>ngx_http_request_t</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4326 Main configuration of a request never changes.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4327 Server configuration may change from a default one after choosing a virtual
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4328 server for a request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4329 Request location configuration may change multiple times as a result of a
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4330 rewrite or internal redirect.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4331 The following example shows how to access HTTP configuration in runtime.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4332 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4333
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4334 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4335 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4336 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	4337 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4338 ngx_http_foo_loc_conf_t *flcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4339
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4340 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	4341
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4342 ...
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 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4345
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4346 </section>
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4349 <section name="Phases" id="http_phases">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4350
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4351 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4352 Each HTTP request passes through a list of HTTP phases.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4353 Each phase is specialized in a particular type of processing.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4354 Most phases allow installing handlers.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4355 The phase handlers are called successively once the request reaches the phase.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4356 Many standard nginx modules install their phase handlers as a way to get called
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4357 at a specific request processing stage.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4358 Following is the list of nginx HTTP phases.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4359 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4360
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4361 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4362
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4363 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4364 <literal>NGX_HTTP_POST_READ_PHASE</literal> is the earliest phase.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4365 The <link doc="../http/ngx_http_realip_module.xml">ngx_http_realip_module</link>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4366 installs its handler at this phase.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4367 This allows to substitute client address before any other module is invoked
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4368 </listitem>
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 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4371 <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal> is used to run rewrite script,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4372 defined at the server level, that is out of any location block.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4373 The
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4374 <link doc="../http/ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4375 installs its handler at this phase
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4376 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4377
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4378 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4379 <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> — a special phase used to choose a
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4380 location based on request URI.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4381 This phase does not allow installing any handlers.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4382 It only performs the default action of choosing a location.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4383 Before this phase, the server default location is assigned to the request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4384 Any module requesting a location configuration, will receive the default server
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4385 location configuration.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4386 After this phase a new location is assigned to the request
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4387 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4388
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4389 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4390 <literal>NGX_HTTP_REWRITE_PHASE</literal> — same as
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4391 <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal>, but for a new location,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	4392 chosen at the previous phase
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4393 </listitem>
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 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4396 <literal>NGX_HTTP_POST_REWRITE_PHASE</literal> — a special phase, used to
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4397 redirect the request to a new location, if the URI was changed during rewrite.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4398 The redirect is done by going back to
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4399 <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4400 No handlers are allowed at this phase
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4401 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4402
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4403 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4404 <literal>NGX_HTTP_PREACCESS_PHASE</literal> — a common phase for different
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4405 types of handlers, not associated with access check.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4406 Standard nginx modules
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4407 <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	4408 </link> and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4409 <link doc="../http/ngx_http_limit_req_module.xml">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4410 ngx_http_limit_req_module</link> register their handlers at this phase
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4411 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4412
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4413 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4414 <literal>NGX_HTTP_ACCESS_PHASE</literal> — used to check access permissions
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4415 for the request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4416 Standard nginx modules such as
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4417 <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	4418 <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	4419 </link> register their handlers at this phase.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4420 If configured so by the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4421 <link doc="../http/ngx_http_core_module.xml" id="satisfy"/> directive, only one
1971 5fb870087b76 Fixed typo and removed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1970 diff changeset	4422 of access phase handlers may allow access to the request in order to continue
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4423 processing
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4424 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4425
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4426 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4427 <literal>NGX_HTTP_POST_ACCESS_PHASE</literal> — a special phase for the
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4428 <link doc="../http/ngx_http_core_module.xml" id="satisfy">satisfy any</link>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4429 case.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4430 If some access phase handlers denied the access and none of them allowed, the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4431 request is finalized.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4432 No handlers are supported at this phase
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4433 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4434
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4435 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4436 <literal>NGX_HTTP_TRY_FILES_PHASE</literal> — a special phase, for the
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4437 <link doc="../http/ngx_http_core_module.xml" id="try_files"/> feature.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4438 No handlers are allowed at this phase
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4439 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4440
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4441 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4442 <literal>NGX_HTTP_CONTENT_PHASE</literal> — a phase, at which the response
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4443 is supposed to be generated.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4444 Multiple nginx standard modules register their handers at this phase, for
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4445 example
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4446 <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	4447 <literal>ngx_http_static_module</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4448 All these handlers are called sequentially until one of them finally produces
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4449 the output.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4450 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	4451 If the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4452 <link doc="../http/ngx_http_core_module.xml">ngx_http_core_module</link>'s
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4453 location configuration has <literal>handler</literal> set, this handler is
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4454 called as the content handler and content phase handlers are ignored
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4455 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4456
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4457 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4458 <literal>NGX_HTTP_LOG_PHASE</literal> is used to perform request logging.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4459 Currently, only the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4460 <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	4461 registers its handler
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4462 at this stage for access logging.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4463 Log phase handlers are called at the very end of request processing, right
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4464 before freeing the request
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4465 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4466
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4467 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4468
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4469 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4470 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	4471 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4472
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4473 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4474 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	4475 NULL, /* preconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4476 ngx_http_foo_init, /* postconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4477
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4478 NULL, /* create main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4479 NULL, /* init main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4480
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4481 NULL, /* create server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4482 NULL, /* merge server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4483
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4484 NULL, /* create location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4485 NULL /* merge location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4486 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4487
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4488
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4489 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4490 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	4491 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4492 ngx_str_t *ua;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4493
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4494 ua = r->headers_in->user_agent;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4495
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4496 if (ua == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4497 return NGX_DECLINED;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4498 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4499
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4500 /* reject requests with "User-Agent: foo" */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4501 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	4502 return NGX_HTTP_FORBIDDEN;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4503 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4504
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4505 return NGX_DECLINED;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4506 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4507
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4508
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4509 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4510 ngx_http_foo_init(ngx_conf_t *cf)
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4511 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4512 ngx_http_handler_pt *h;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4513 ngx_http_core_main_conf_t *cmcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4514
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4515 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	4516
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4517 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	4518 if (h == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4519 return NGX_ERROR;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4520 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4521
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4522 *h = ngx_http_foo_handler;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4523
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4524 return NGX_OK;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4525 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4526 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4527
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4528 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4529 Phase handlers are expected to return specific codes:
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4530 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4531
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4532 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4533
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4534 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4535 <literal>NGX_OK</literal> — proceed to the next phase
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4536 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4537
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4538 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4539 <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	4540 phase.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4541 If current handler is the last in current phase, move to the next phase
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4542 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4543
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4544 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4545 <literal>NGX_AGAIN, NGX_DONE</literal> — suspend phase handling until some
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4546 future event.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4547 This can be for example asynchronous I/O operation or just a delay.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4548 It is supposed, that phase handling will be resumed later by calling
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4549 <literal>ngx_http_core_run_phases()</literal>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4550 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4551
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4552 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4553 Any other value returned by the phase handler is treated as a request
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4554 finalization code, in particular, HTTP response code.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4555 The request is finalized with the code provided
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4556 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4557
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4558 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4559
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4560 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4561 Some phases treat return codes in a slightly different way.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4562 At content phase, any return code other that <literal>NGX_DECLINED</literal>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4563 is considered a finalization code.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4564 As for the location content handlers, any return from them is considered a
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4565 finalization code.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4566 At access phase, in
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4567 <link doc="../http/ngx_http_core_module.xml" id="satisfy">satisfy any</link>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4568 mode, returning a code other
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4569 than <literal>NGX_OK, NGX_DECLINED, NGX_AGAIN, NGX_DONE</literal> is considered
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4570 a denial.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4571 If none of future access handlers allow access or deny with a new
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4572 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	4573 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4574
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4575 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4576
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	4577
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4578 <section name="Variables" id="http_variables">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4579
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4580 <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	4581
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4582 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4583 Variables may be referenced using index (this is the most common method)
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4584 or names (see below in the section about creating variables).
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4585 Index is created at configuration stage, when a variable is added
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4586 to configuration.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4587 The variable index can be obtained using
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4588 <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	4589 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4590 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	4591 ngx_int_t index;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4592
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4593 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	4594 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4595 Here, the <literal>cf</literal> is a pointer to nginx configuration and the
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4596 <literal>name</literal> points to a string with the variable name.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4597 The function returns <literal>NGX_ERROR</literal> on error or valid index
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4598 otherwise, which is typically stored somewhere in a module configuration for
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4599 future use.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4600 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4601
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4602 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4603 All HTTP variables are evaluated in the context of HTTP request and results
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4604 are specific to and cached in HTTP request.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4605 All functions that evaluate variables return
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4606 <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	4607 the variable value:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4608 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4609 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	4610
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4611 typedef struct {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4612 unsigned len:28;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4613
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4614 unsigned valid:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4615 unsigned no_cacheable:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4616 unsigned not_found:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4617 unsigned escape:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4618
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4619 u_char *data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4620 } ngx_variable_value_t;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4621 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4622 where:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4623 <list type="bullet">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4624
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4625 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4626 <literal>len</literal> — length of a value
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4627 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4628
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4629 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4630 <literal>data</literal> — value itself
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4631 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4632
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4633 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4634 <literal>valid</literal> — value is valid
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4635 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4636
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4637 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4638 <literal>not_found</literal> — variable was not found and thus
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4639 the <literal>data</literal> and <literal>len</literal> fields are irrelevant;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4640 this may happen, for example, with such variables as <var>$arg_foo</var>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4641 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	4642 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4643
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4644 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4645 <literal>no_cacheable</literal> — do not cache result
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4646 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4647
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4648 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4649 <literal>escape</literal> — used internally by the logging module to mark
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4650 values that require escaping on output
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4651 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4652
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4653 </list>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4654 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4655
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4656 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4657 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	4658 and <literal>ngx_http_get_indexed_variable()</literal> functions
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4659 are used to obtain the variable value.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4660 They have the same interface - accepting a HTTP request <literal>r</literal>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4661 as a context for evaluating the variable and an <literal>index</literal>,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4662 identifying it.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4663 Example of typical usage:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4664 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4665 ngx_http_variable_value_t *v;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4666
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4667 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	4668
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4669 if (v == NULL \|\| v->not_found) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4670 /* 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	4671 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4672 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4673
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4674 /* some meaningful value is found */
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4675 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4676 The difference between functions is that the
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4677 <literal>ngx_http_get_indexed_variable()</literal> returns cached value
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4678 and <literal>ngx_http_get_flushed_variable()</literal> flushes cache for
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4679 non-cacheable variables.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4680 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4681
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4682 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4683 There are cases when it is required to deal with variables which names are
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4684 not known at configuration time and thus they cannot be accessed using indexes,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4685 for example in modules like SSI or Perl.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4686 The <literal>ngx_http_get_variable(r, name, key)</literal> function may be
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4687 used in such cases.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4688 It searches for the <literal>variable</literal> with a given
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4689 <literal>name</literal> and its hash <literal>key</literal>.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4690 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4691
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4692 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4693
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4694
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4695 <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	4696
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4697 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4698 To create a variable <literal>ngx_http_add_variable()</literal> function
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4699 is used.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4700 It takes configuration (where variable is registered), variable name and
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4701 flags that control its behaviour:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4702
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4703 <list type="bullet">
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	4704 <listitem><literal>NGX_HTTP_VAR_CHANGEABLE</literal> — allows redefining
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4705 the variable; If another module will define a variable with such name,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4706 no conflict will happen.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4707 For example, this allows user to override variables using the
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4708 <link doc="../http/ngx_http_rewrite_module.xml" id="set"/> directive.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4709 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4710
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	4711 <listitem><literal>NGX_HTTP_VAR_NOCACHEABLE</literal> — disables caching,
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4712 is useful for such variables as <literal>$time_local</literal>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4713 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4714
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	4715 <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	4716 this variable is only accessible by index, not by name.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4717 This is a small optimization which may be used when it is known that the
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4718 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	4719 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4720
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	4721 <listitem><literal>NGX_HTTP_VAR_PREFIX</literal> — the name of this
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4722 variable is a prefix.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4723 A handler must implement additional logic to obtain value of specific
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4724 variable.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4725 For example, all “<literal>arg_</literal>” variables are processed by the
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4726 same handler which performs lookup in request arguments and returns value
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4727 of specific argument.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4728 </listitem>
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 </list>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4731
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4732 The function returns NULL in case of error or a pointer to
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4733 <literal>ngx_http_variable_t</literal>:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4734 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4735 struct ngx_http_variable_s {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4736 ngx_str_t name;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4737 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	4738 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	4739 uintptr_t data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4740 ngx_uint_t flags;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4741 ngx_uint_t index;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4742 };
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4743 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4744
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4745 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	4746 are called to obtain or set the variable value,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4747 <literal>data</literal> will be passed to variable handlers,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4748 <literal>index</literal> will hold assigned variable index, used to reference
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4749 the variable.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4750 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4751
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4752 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4753 Usually, a null-terminated static array of such structures is created
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4754 by a module and processed at the preconfiguration stage to add variables
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4755 into configuration:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4756 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4757 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	4758
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4759 { ngx_string("foo_v1"), NULL, ngx_http_foo_v1_variable, NULL, 0, 0 },
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 { ngx_null_string, NULL, NULL, 0, 0, 0 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4762 };
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4763
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4764 static ngx_int_t
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4765 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	4766 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4767 ngx_http_variable_t var, v;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4768
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4769 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	4770 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	4771 if (var == NULL) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4772 return NGX_ERROR;
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
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4775 var->get_handler = v->get_handler;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4776 var->data = v->data;
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 return NGX_OK;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4780 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4781 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4782 This function is used to initialize the <literal>preconfiguration</literal>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4783 field of the HTTP module context and is called before parsing HTTP configuration,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4784 so it could refer to these 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>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4788 The <literal>get</literal> handler is responsible for evaluating the variable
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4789 in a context of specific request, for example:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4790 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4791 static ngx_int_t
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4792 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	4793 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	4794 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4795 u_char *p;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4796
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4797 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	4798 if (p == NULL) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4799 return NGX_ERROR;
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
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4802 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	4803 v->valid = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4804 v->no_cacheable = 0;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4805 v->not_found = 0;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4806 v->data = p;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4807
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4808 return NGX_OK;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4809 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4810 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4811 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	4812 (for example, failed memory allocation) or <literal>NGX_OK</literal> otherwise.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4813 The status of variable evaluation may be understood by inspecting flags
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4814 of the <literal>ngx_http_variable_value_t</literal> (see description above).
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4815 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4816
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4817 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4818 The <literal>set</literal> handler allows setting the property
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4819 referred by the variable.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4820 For example, the <literal>$limit_rate</literal> variable set handler
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4821 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	4822 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4823 ...
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4824 { 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	4825 ngx_http_variable_request_get_size,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4826 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	4827 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	4828 ...
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4829
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4830 static void
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4831 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	4832 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	4833 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4834 ssize_t s, *sp;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4835 ngx_str_t val;
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 val.len = v->len;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4838 val.data = v->data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4839
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4840 s = ngx_parse_size(&val);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4841
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4842 if (s == NGX_ERROR) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4843 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	4844 "invalid size \"%V\"", &val);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4845 return;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4846 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4847
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4848 sp = (ssize_t ) ((char ) r + data);
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 *sp = s;
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 return;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4853 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4854 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4855
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4856 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4857
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4858 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4859
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4860 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4861
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4862
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4863 <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	4864
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4865 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4866 A complex value, despite its name, provides an easy way to evaluate
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4867 expressions that may contain text, variables, and their combination.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4868 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4869
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4870 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4871 The complex value description in
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4872 <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	4873 configuration stage into <literal>ngx_http_complex_value_t</literal>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4874 which is used at runtime to obtain evaluated expression results.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4875
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4876 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4877 ngx_str_t *value;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4878 ngx_http_complex_value_t cv;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4879 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	4880
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4881 value = cf->args->elts; /* directive arguments */
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 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	4884
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4885 ccv.cf = cf;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4886 ccv.value = &value[1];
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4887 ccv.complex_value = &cv;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4888 ccv.zero = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4889 ccv.conf_prefix = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4890
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4891 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	4892 return NGX_CONF_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4893 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4894 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4895
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4896 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	4897 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	4898
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4899 <list type="bullet">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4900
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4901 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4902 <literal>cf</literal> — configuration pointer
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4903 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4904
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4905 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4906 <literal>value</literal> — string for parsing (input)
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4907 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4908
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4909 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4910 <literal>complex_value</literal> — compiled value (output)
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4911 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4912
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4913 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4914 <literal>zero</literal> — flag that enables zero-terminating value
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4915 </listitem>
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 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4918 <literal>conf_prefix</literal> — prefixes result with configuration prefix
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4919 (the directory where nginx is currently looking for configuration)
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4920 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4921
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4922 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4923 <literal>root_prefix</literal> — prefixes result with root prefix
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4924 (this is the normal nginx installation prefix)
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4925 </listitem>
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 </list>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4928 The <literal>zero</literal> flag is usable when results are to be passed to
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4929 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	4930 dealing with filenames.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4931 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4932
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4933 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4934 Upon successful compilation, <literal>cv.lengths</literal> may
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4935 be inspected to get information about the presence of variables
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4936 in the expression.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4937 The NULL value means that the expression contained static text only,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4938 and there is no need in storing it as a complex value,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4939 so a simple string can be used.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4940 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4941
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4942 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4943 The <literal>ngx_http_set_complex_value_slot()</literal> is a convenient
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4944 function used to initialize complex value completely right in the directive
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4945 declaration.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4946 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4947
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4948 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4949 At runtime, a complex value may be calculated using the
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4950 <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	4951 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4952 ngx_str_t res;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4953
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4954 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	4955 return NGX_ERROR;
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 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4958 Given the request <literal>r</literal> and previously compiled
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4959 value <literal>cv</literal> the function will evaluate
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4960 expression and put result into <literal>res</literal>.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4961 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4962
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4963 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4964
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4965
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4966 <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	4967
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4968 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4969 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	4970 <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	4971 structure.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4972 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	4973 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	4974 <literal>ngx_http_get_module_loc_conf(r, module)</literal>.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4975 Request location may be changed several times throughout its lifetime.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4976 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	4977 request.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4978 Once a request switches to a different server (chosen by the HTTP
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4979 <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	4980 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	4981 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	4982 <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	4983 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	4984 configured for the server.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4985 The
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4986 <link doc="../http/ngx_http_rewrite_module.xml">ngx_http_rewrite_module</link>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4987 may change the request URI at the
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4988 <literal>NGX_HTTP_REWRITE_PHASE</literal> request phase as a result of
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4989 <link doc="../http/ngx_http_rewrite_module.xml" id="rewrite">rewrite</link> and
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4990 return to the <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal> phase for choosing a
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4991 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	4992 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4993
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4994 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4995 It is also possible to redirect a request to a new location at any point by
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4996 calling one of the functions
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4997 <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	4998 <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	4999 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5000
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5001 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5002 The function <literal>ngx_http_internal_redirect(r, uri, args)</literal> changes
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5003 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	5004 <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	5005 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	5006 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	5007 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	5008 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5009
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5010 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5011 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	5012 arguments.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5013 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5014
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5015 <programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5016 ngx_int_t
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5017 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	5018 {
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5019 ngx_str_t uri, args;
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5020
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5021 ngx_str_set(&uri, "/foo");
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5022 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	5023
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5024 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	5025 }
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5026 </programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5027
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5028 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5029 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	5030 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	5031 argument.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5032 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	5033 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	5034 <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	5035 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5036
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5037 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5038 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	5039 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5040
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5041 <programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5042 ngx_int_t
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5043 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	5044 {
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5045 ngx_str_t name;
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5046
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5047 ngx_str_set(&name, "foo");
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5048
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5049 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	5050 }
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5051 </programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5052
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5053 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5054 Both functions <literal>ngx_http_internal_redirect(r, uri, args)</literal>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5055 and <literal>ngx_http_named_location(r, name)</literal> may be called when
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5056 a request already has some contexts saved in its <literal>ctx</literal> field
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5057 by nginx modules.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5058 These contexts could become inconsistent with the new
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5059 location configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5060 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	5061 erased by both redirect functions.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5062 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5063
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5064 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5065 Redirected and rewritten requests become internal and may access the
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5066 <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	5067 locations.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5068 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	5069 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5070
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5071 </section>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5072
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5073
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5074 <section name="Subrequests" id="http_subrequests">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5075
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5076 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5077 Subrequests are primarily used to include output of one request into another,
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5078 possibly mixed with other data.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5079 A subrequest looks like a normal request, but shares some data with its parent.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5080 Particularly, all fields related to client input are shared since a subrequest
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5081 does not receive any other input from client.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5082 The request field <literal>parent</literal> for a subrequest keeps a link to its
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5083 parent request and is NULL for the main request.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5084 The field <literal>main</literal> keeps a link to the main request in a group of
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5085 requests.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5086 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5087
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5088 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5089 A subrequest starts with <literal>NGX_HTTP_SERVER_REWRITE_PHASE</literal> phase.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5090 It passes through the same phases as a normal request and is assigned a location
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5091 based on its own URI.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5092 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5093
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5094 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5095 Subrequest output header is always ignored.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5096 Subrequest output body is placed by the
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5097 <literal>ngx_http_postpone_filter</literal> into the right position in relation
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5098 to other data produced by the parent request.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5099 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5100
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5101 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5102 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	5103 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	5104 <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	5105 connection object.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5106 At any point, only the active request in a request group is allowed to output
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5107 its buffers to the client.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5108 A non-active request can still send its data to the filter chain, but they
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5109 will not pass beyond the <literal>ngx_http_postpone_filter</literal> and will
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5110 remain buffered by that filter until the request becomes active.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5111 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	5112 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5113
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5114 <list type="bullet">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5115
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5116 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5117 Initially, the main request is active
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5118 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5119
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5120 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5121 The first subrequest of an active request becomes active right after creation
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5122 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5123
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5124 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5125 The <literal>ngx_http_postpone_filter</literal> activates the next request
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5126 in active request's subrequest list, once all data prior to that request are
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5127 sent
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5128 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5129
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5130 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5131 When a request is finalized, its parent is activated
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5132 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5133
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5134 </list>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5135
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5136 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5137 A subrequest is created by calling the function
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5138 <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	5139 <literal>r</literal> is the parent request, <literal>uri</literal> and
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5140 <literal>args</literal> are URI and arguments of the
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5141 subrequest, <literal>psr</literal> is the output parameter, receiving the
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5142 newly created subrequest reference, <literal>ps</literal> is a callback object
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5143 for notifying the parent request that the subrequest is being finalized,
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5144 <literal>flags</literal> is subrequest creation flags bitmask.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5145 The following flags are available:
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5146 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5147
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5148 <list type="bullet">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5149
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5150 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5151 <literal>NGX_HTTP_SUBREQUEST_IN_MEMORY</literal> - subrequest output should not
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5152 be sent to the client, but rather stored in memory.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5153 This only works for proxying subrequests.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5154 After subrequest finalization its output is available in
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5155 <literal>r->upstream->buffer</literal> buffer of type
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5156 <literal>ngx_buf_t</literal>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5157 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5158
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5159 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5160 <literal>NGX_HTTP_SUBREQUEST_WAITED</literal> - the subrequest
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5161 <literal>done</literal> flag is set even if it is finalized being non-active.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5162 This subrequest flag is used by the SSI filter
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5163 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5164
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5165 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5166 <literal>NGX_HTTP_SUBREQUEST_CLONE</literal> - the subrequest is created as a
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5167 clone of its parent.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5168 It is started at the same location and proceeds from the same phase as the
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5169 parent request
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5170 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5171
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5172 </list>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5173
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5174 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5175 The following example creates a subrequest with the URI of "/foo".
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5176 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5177
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5178 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5179 ngx_int_t rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5180 ngx_str_t uri;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5181 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5182
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5183 ...
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5184
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5185 ngx_str_set(&uri, "/foo");
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5186
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5187 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	5188 if (rc == NGX_ERROR) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5189 /* error */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5190 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5191 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5192
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5193 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5194 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	5195 subrequest.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5196 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5197
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5198 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5199 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5200 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	5201 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5202 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5203 ngx_http_post_subrequest_t *ps;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5204
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5205 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	5206 if (ps == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5207 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5208 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5209
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5210 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	5211 ps->data = "foo";
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5212
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5213 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	5214 NGX_HTTP_SUBREQUEST_CLONE);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5215 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5216
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5217
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5218 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5219 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	5220 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5221 char msg = (char ) data;
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 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	5224 "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	5225
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5226 return rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5227 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5228 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5229
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5230 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5231 Subrequests are normally created in a body filter.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5232 In this case subrequest output can be treated as any other explicit request
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5233 output.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5234 This means that eventually the output of a subrequest is sent to the client
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5235 after all explicit buffers passed prior to subrequest creation and before any
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5236 buffers passed later.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5237 This ordering is preserved even for large hierarchies of subrequests.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5238 The following example inserts a subrequest output after all request data
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5239 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	5240 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5241
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5242 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5243 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5244 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	5245 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5246 ngx_int_t rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5247 ngx_buf_t *b;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5248 ngx_uint_t last;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5249 ngx_chain_t *cl, out;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5250 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5251 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	5252
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5253 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	5254 if (ctx == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5255 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	5256 }
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 last = 0;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5259
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5260 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	5261 if (cl->buf->last_buf) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5262 cl->buf->last_buf = 0;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5263 cl->buf->last_in_chain = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5264 cl->buf->sync = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5265 last = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5266 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5267 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5268
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5269 /* Output explicit output buffers */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5270
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5271 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	5272
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5273 if (rc == NGX_ERROR \|\| !last) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5274 return rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5275 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5276
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5277 /*
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5278 * 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	5279 * 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	5280 * 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	5281 */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5282
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5283 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	5284 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5285 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5286
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5287 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	5288
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5289
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5290 /* 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	5291
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5292 b = ngx_calloc_buf(r->pool);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5293 if (b == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5294 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5295 }
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 b->last_buf = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5298
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5299 out.buf = b;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5300 out.next = NULL;
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 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	5303 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5304 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5305
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5306 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5307 A subrequest may also be created for other purposes than data output.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5308 For example, the <link doc="../http/ngx_http_auth_request_module.xml">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5309 ngx_http_auth_request_module</link>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5310 creates a subrequest at <literal>NGX_HTTP_ACCESS_PHASE</literal> phase.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5311 To disable any output at this point, the subrequest
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5312 <literal>header_only</literal> flag is set.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5313 This prevents subrequest body from being sent to the client.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5314 Its header is ignored anyway.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5315 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	5316 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5317
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5318 </section>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5319
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5320
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5321 <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	5322
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5323 <para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5324 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	5325 <literal>ngx_http_finalize_request(r, rc)</literal>.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5326 It is usually finalized by the content handler after sending all output buffers
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5327 to the filter chain.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5328 At this point the output may not be completely sent to the client, but remain
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5329 buffered somewhere along the filter chain.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5330 If it is, the <literal>ngx_http_finalize_request(r, rc)</literal> function will
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5331 automatically install a special handler <literal>ngx_http_writer(r)</literal>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5332 to finish sending the output.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5333 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	5334 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	5335 </para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5336
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5337 <para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5338 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	5339 following <literal>rc</literal> values:
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5340 </para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5341
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5342 <list type="bullet">
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5343
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5344 <listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5345 <literal>NGX_DONE</literal> - fast finalization.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5346 Decrement request <literal>count</literal> and destroy the request if it
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5347 reaches zero.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5348 The client connection may still be used for more requests after that
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5349 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5350
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5351 <listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5352 <literal>NGX_ERROR</literal>, <literal>NGX_HTTP_REQUEST_TIME_OUT</literal>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5353 (408), <literal>NGX_HTTP_CLIENT_CLOSED_REQUEST</literal> (499) - error
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5354 finalization.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5355 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	5356 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5357
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5358 <listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5359 <literal>NGX_HTTP_CREATED</literal> (201),
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5360 <literal>NGX_HTTP_NO_CONTENT</literal> (204), codes greater than or equal to
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5361 <literal>NGX_HTTP_SPECIAL_RESPONSE</literal> (300) - special response
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5362 finalization.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5363 For these values nginx either sends a default code response page to the client
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5364 or performs the internal redirect to an
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5365 <link doc="../http/ngx_http_core_module.xml" id="error_page"/> location if it's
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5366 configured for the code
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5367 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5368
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5369 <listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5370 Other codes are considered success finalization codes and may activate the
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5371 request writer to finish sending the response body.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5372 Once body is completely sent, request <literal>count</literal> is decremented.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5373 If it reaches zero, the request is destroyed, but the client connection may
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5374 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	5375 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	5376 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	5377 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5378
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5379 </list>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5380
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5381 </section>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5382
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5383
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5384 <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	5385
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5386 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5387 For dealing with client request body, nginx provides the following functions:
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5388 <literal>ngx_http_read_client_request_body(r, post_handler)</literal> and
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5389 <literal>ngx_http_discard_request_body(r)</literal>.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5390 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	5391 <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	5392 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	5393 body.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5394 One of these functions must be called for every request.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5395 Normally, it is done in the content handler.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5396 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5397
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5398 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5399 Reading or discarding client request body from a subrequest is not allowed.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5400 It should always be done in the main request.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5401 When a subrequest is created, it inherits the parent
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5402 <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	5403 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	5404 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5405
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5406 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5407 The function
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5408 <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	5409 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	5410 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	5411 is called to continue processing the request.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5412 If request body is missing or already read, the callback is called immediately.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5413 The function
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5414 <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	5415 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	5416 <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	5417 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	5418 chain.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5419 The body can be saved in memory buffers or file buffers, if
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5420 <link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5421 is not enough to fit the entire body in memory.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5422 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5423
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5424 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5425 The following example reads client request body and returns its size.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5426 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5427
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5428 <programlisting>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5429 ngx_int_t
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5430 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	5431 {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5432 ngx_int_t rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5433
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5434 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	5435
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5436 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	5437 /* error */
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5438 return rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5439 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5440
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5441 return NGX_DONE;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5442 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5443
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5444
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5445 void
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5446 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	5447 {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5448 off_t len;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5449 ngx_buf_t *b;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5450 ngx_int_t rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5451 ngx_chain_t *in, out;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5452
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5453 if (r->request_body == NULL) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5454 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	5455 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5456 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5457
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5458 len = 0;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5459
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5460 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	5461 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	5462 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5463
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5464 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	5465 if (b == NULL) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5466 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	5467 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5468 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5469
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5470 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	5471 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	5472 b->last_in_chain = 1;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5473
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5474 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	5475 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	5476
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5477 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	5478
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5479 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	5480 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	5481 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5482 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5483
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5484 out.buf = b;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5485 out.next = NULL;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5486
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5487 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	5488
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5489 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	5490 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5491 </programlisting>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5492
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5493 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5494 The following fields of the request affect the way request body is read:
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5495 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5496
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5497 <list type="bullet">
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5498
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5499 <listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5500 <literal>request_body_in_single_buf</literal> - read body to a single memory
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5501 buffer
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5502 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5503
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5504 <listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5505 <literal>request_body_in_file_only</literal> - always read body to a file,
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5506 even if fits the memory buffer
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5507 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5508
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5509 <listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5510 <literal>request_body_in_persistent_file</literal> - do not unlink the file
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5511 right after creation.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5512 Such a file can be moved to another directory
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5513 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5514
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5515 <listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5516 <literal>request_body_in_clean_file</literal> - unlink the file the when the
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5517 request is finalized.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5518 This can be useful when a file was supposed to be moved to another directory
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5519 but eventually was not moved for some reason
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5520 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5521
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5522 <listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5523 <literal>request_body_file_group_access</literal> - enable file group access.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5524 By default a file is created with 0600 access mask.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5525 When the flag is set, 0660 access mask is used
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5526 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5527
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5528 <listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5529 <literal>request_body_file_log_level</literal> - log file errors with this
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5530 log level
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5531 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5532
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5533 <listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5534 <literal>request_body_no_buffering</literal> - read request body without
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5535 buffering
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5536 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5537
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5538 </list>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5539
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5540 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5541 When the <literal>request_body_no_buffering</literal> flag is set, the
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5542 unbuffered mode of reading the request body is enabled.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5543 In this mode, after calling
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5544 <literal>ngx_http_read_client_request_body()</literal>, the
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5545 <literal>bufs</literal> chain may keep only a part of the body.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5546 To read the next part, the
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5547 <literal>ngx_http_read_unbuffered_request_body(r)</literal> function should be
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5548 called.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5549 The return value of <literal>NGX_AGAIN</literal> and the request flag
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5550 <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	5551 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	5552 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	5553 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	5554 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	5555 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5556
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5557 </section>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5558
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5559
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5560 <section name="Response" id="http_response">
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5561
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5562 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5563 An HTTP response in nginx is produced by sending the response header followed by
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5564 the optional response body.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5565 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	5566 written to the client socket.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5567 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	5568 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	5569 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5570
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5571
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5572 <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	5573
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5574 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5575 Output header is sent by the function
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5576 <literal>ngx_http_send_header(r)</literal>.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5577 Prior to calling this function, <literal>r->headers_out</literal> should contain
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5578 all the data required to produce the HTTP response header.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5579 It's always required to set the <literal>status</literal> field of
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5580 <literal>r->headers_out</literal>.
1971 5fb870087b76 Fixed typo and removed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1970 diff changeset	5581 If the response status suggests 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	5582 <literal>content_length_n</literal> can be set as well.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5583 The default value for this field is -1, which means that the body size is
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5584 unknown.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5585 In this case, chunked transfer encoding is used.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5586 To output an arbitrary header, <literal>headers</literal> list should be
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5587 appended.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5588 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5589
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5590 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5591 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5592 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	5593 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5594 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5595 ngx_table_elt_t *h;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5596
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5597 /* send header */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5598
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5599 r->headers_out.status = NGX_HTTP_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5600 r->headers_out.content_length_n = 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5601
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5602 /* X-Foo: foo */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5603
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5604 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	5605 if (h == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5606 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5607 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5608
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5609 h->hash = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5610 ngx_str_set(&h->key, "X-Foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5611 ngx_str_set(&h->value, "foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5612
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5613 rc = ngx_http_send_header(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5614
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5615 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	5616 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5617 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5618
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5619 /* send body */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5620
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5621 ...
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5622 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5623 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5624
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5625 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5626
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5627
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5628 <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	5629
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5630 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5631 The <literal>ngx_http_send_header(r)</literal> function invokes the header
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5632 filter chain by calling the top header filter handler
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5633 <literal>ngx_http_top_header_filter</literal>.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5634 It's assumed that every header handler calls the next handler in chain until
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5635 the final handler <literal>ngx_http_header_filter(r)</literal> is called.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5636 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	5637 <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	5638 <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	5639 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5640
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5641 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5642 To add a handler to the header filter chain, one should store its address in
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5643 <literal>ngx_http_top_header_filter</literal> global variable at configuration
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5644 time.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5645 The previous handler address is normally stored in a module's static variable
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5646 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	5647 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5648
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5649 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5650 The following is an example header filter module, adding the HTTP header
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5651 "X-Foo: foo" to every output with the status 200.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5652 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5653
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5654 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5655 #include <ngx_config.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5656 #include <ngx_core.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5657 #include <ngx_http.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5658
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5659
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5660 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	5661 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	5662
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5663
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5664 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	5665 NULL, /* preconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5666 ngx_http_foo_header_filter_init, /* postconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5667
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5668 NULL, /* create main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5669 NULL, /* init main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5670
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5671 NULL, /* create server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5672 NULL, /* merge server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5673
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5674 NULL, /* create location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5675 NULL /* merge location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5676 };
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5677
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5678
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5679 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	5680 NGX_MODULE_V1,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5681 &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	5682 NULL, /* module directives */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5683 NGX_HTTP_MODULE, /* module type */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5684 NULL, /* init master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5685 NULL, /* init module */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5686 NULL, /* init process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5687 NULL, /* init thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5688 NULL, /* exit thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5689 NULL, /* exit process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5690 NULL, /* exit master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5691 NGX_MODULE_V1_PADDING
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5692 };
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5693
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 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	5696
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 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5699 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	5700 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5701 ngx_table_elt_t *h;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5702
1971 5fb870087b76 Fixed typo and removed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1970 diff changeset	5703 /*
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5704 * 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	5705 * to every HTTP 200 response
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5706 */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5707
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5708 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	5709 return ngx_http_next_header_filter(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5710 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5711
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5712 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	5713 if (h == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5714 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5715 }
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 h->hash = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5718 ngx_str_set(&h->key, "X-Foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5719 ngx_str_set(&h->value, "foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5720
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5721 return ngx_http_next_header_filter(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5722 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5723
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5724
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5725 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5726 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	5727 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5728 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	5729 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	5730
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5731 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5732 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5733 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5734
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5735 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5736
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5737 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5738
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5739
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5740 <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	5741
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5742 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5743 Response body is sent by calling the function
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5744 <literal>ngx_http_output_filter(r, cl)</literal>.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5745 The function can be called multiple times.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5746 Each time it sends a part of the response body passed as a buffer chain.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5747 The last body buffer should have the <literal>last_buf</literal> flag set.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5748 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5749
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5750 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5751 The following example produces a complete HTTP output with "foo" as its body.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5752 In order for the example to work not only as a main request but as a subrequest
1980 5718cf42be55 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1979 diff changeset	5753 as well, 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	5754 of the output.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5755 The <literal>last_buf</literal> flag is set only for the main request since
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5756 a subrequest's last buffers does not end the entire output.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5757 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5758
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5759 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5760 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5761 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	5762 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5763 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5764 ngx_buf_t *b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5765 ngx_chain_t out;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5766
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5767 /* send header */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5768
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5769 r->headers_out.status = NGX_HTTP_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5770 r->headers_out.content_length_n = 3;
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 rc = ngx_http_send_header(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5773
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5774 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	5775 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5776 }
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 /* send body */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5779
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5780 b = ngx_calloc_buf(r->pool);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5781 if (b == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5782 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5783 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5784
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5785 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	5786 b->last_in_chain = 1;
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 b->memory = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5789
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5790 b->pos = (u_char *) "foo";
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5791 b->last = b->pos + 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5792
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5793 out.buf = b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5794 out.next = NULL;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5795
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5796 return ngx_http_output_filter(r, &out);
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 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5799
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5800 </section>
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 <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	5804
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5805 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5806 The function <literal>ngx_http_output_filter(r, cl)</literal> invokes the
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5807 body filter chain by calling the top body filter handler
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5808 <literal>ngx_http_top_body_filter</literal>.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5809 It's assumed that every body handler calls the next handler in chain until
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5810 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	5811 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5812
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5813 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5814 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	5815 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	5816 the next handler.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5817 It's worth noting that the chain links <literal>ngx_chain_t</literal> of the
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5818 incoming chain belong to the caller.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5819 They should never be reused or changed.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5820 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	5821 to keep track of the buffers it has sent.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5822 To save the buffer chain or to substitute some buffers before sending further,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5823 a handler should allocate its own chain links.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5824 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5825
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5826 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5827 Following is the example of a simple body filter counting the number of
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5828 body bytes.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5829 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	5830 used in the access log.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5831 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5832
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5833 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5834 #include <ngx_config.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5835 #include <ngx_core.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5836 #include <ngx_http.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5837
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5838
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5839 typedef struct {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5840 off_t count;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5841 } ngx_http_counter_filter_ctx_t;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5842
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5843
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5844 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	5845 ngx_chain_t *in);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5846 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	5847 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	5848 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	5849 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	5850
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 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	5853 ngx_http_counter_add_variables, /* preconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5854 ngx_http_counter_filter_init, /* postconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5855
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5856 NULL, /* create main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5857 NULL, /* init main configuration */
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 NULL, /* create server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5860 NULL, /* merge server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5861
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5862 NULL, /* create location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5863 NULL /* merge location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5864 };
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5867 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	5868 NGX_MODULE_V1,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5869 &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	5870 NULL, /* module directives */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5871 NGX_HTTP_MODULE, /* module type */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5872 NULL, /* init master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5873 NULL, /* init module */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5874 NULL, /* init process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5875 NULL, /* init thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5876 NULL, /* exit thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5877 NULL, /* exit process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5878 NULL, /* exit master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5879 NGX_MODULE_V1_PADDING
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5880 };
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5881
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 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	5884
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5885 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	5886
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5887
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5888 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5889 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	5890 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5891 ngx_chain_t *cl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5892 ngx_http_counter_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5893
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5894 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	5895 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5896 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	5897 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5898 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5899 }
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 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	5902 }
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 for (cl = in; cl; cl = cl->next) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5905 ctx->count += ngx_buf_size(cl->buf);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5906 }
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 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	5909 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5910
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5911
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5912 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5913 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	5914 uintptr_t data)
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5915 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5916 u_char *p;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5917 ngx_http_counter_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5918
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5919 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	5920 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5921 v->not_found = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5922 return NGX_OK;
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5925 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	5926 if (p == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5927 return NGX_ERROR;
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5930 v->data = p;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5931 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	5932 v->valid = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5933 v->no_cacheable = 0;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5934 v->not_found = 0;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5935
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5936 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5937 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5938
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5939
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5940 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5941 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	5942 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5943 ngx_http_variable_t *var;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5944
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5945 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	5946 if (var == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5947 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5948 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5949
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5950 var->get_handler = ngx_http_counter_variable;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5951
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5952 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5953 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5954
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 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5957 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	5958 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5959 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	5960 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	5961
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5962 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5963 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5964 </programlisting>
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 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5967
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5968
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5969 <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	5970
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5971 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5972 When writing a body or header filter, a special care should be taken of the
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5973 filters order.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5974 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	5975 modules.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5976 It's important to register a filter module in the right place in respect to
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5977 other filters.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5978 Normally, filters are registered by modules in their postconfiguration handlers.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5979 The order in which filters are called is obviously the reverse of when they are
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5980 registered.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5981 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5982
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5983 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5984 A special slot <literal>HTTP_AUX_FILTER_MODULES</literal> for third-party filter
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5985 modules is provided by nginx.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5986 To register a filter module in this slot, the <literal>ngx_module_type</literal>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5987 variable should be set to the value of <literal>HTTP_AUX_FILTER</literal> in
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5988 module's configuration.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5989 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5990
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5991 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5992 The following example shows a filter module config file assuming it only has
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5993 one source file <literal>ngx_http_foo_filter_module.c</literal>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5994 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5995
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5996 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5997 ngx_module_type=HTTP_AUX_FILTER
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5998 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	5999 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	6000
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6001 . auto/module
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6002 </programlisting>
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 </section>
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6007 <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	6008
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6009 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6010 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	6011 allocated buffers.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6012 A standard approach widely adopted in nginx code is to keep two buffer chains
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6013 for this purpose: <literal>free</literal> and <literal>busy</literal>.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6014 The <literal>free</literal> chain keeps all free buffers.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6015 These buffers can be reused.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6016 The <literal>busy</literal> chain keeps all buffers sent by the current
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6017 module which are still in use by some other filter handler.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6018 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	6019 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	6020 (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	6021 <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	6022 Once a buffer is completely consumed, it's ready to be reused.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6023 To update the <literal>free</literal> chain with newly freed buffers,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6024 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	6025 size buffers at the head of it to <literal>free</literal>.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6026 This operation is so common that there is a special function
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6027 <literal>ngx_chain_update_chains(free, busy, out, tag)</literal> which does
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6028 this.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6029 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	6030 <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	6031 <literal>busy</literal> to <literal>free</literal>.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6032 Only the buffers with the given <literal>tag</literal> are reused.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6033 This lets a module reuse only the buffers allocated by itself.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6034 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6035
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6036 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6037 The following example is a body filter inserting the “foo” string before each
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6038 incoming buffer.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6039 The new buffers allocated by the module are reused if possible.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6040 Note that for this example to work properly, it's also required to set up a
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6041 header filter and reset <literal>content_length_n</literal> to -1, which is
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6042 beyond the scope of this section.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6043 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6044
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6045 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6046 typedef struct {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6047 ngx_chain_t *free;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6048 ngx_chain_t *busy;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6049 } ngx_http_foo_filter_ctx_t;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6050
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 ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6053 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	6054 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6055 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6056 ngx_buf_t *b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6057 ngx_chain_t cl, tl, out, *ll;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6058 ngx_http_foo_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6059
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6060 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	6061 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6062 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	6063 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6064 return NGX_ERROR;
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6067 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	6068 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6069
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6070 /* 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	6071
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6072 ll = &out;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6073
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6074 for (cl = in; cl; cl = cl->next) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6075
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6076 /* 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	6077
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6078 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	6079 if (tl == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6080 return NGX_ERROR;
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6083 b = tl->buf;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6084 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	6085 b->memory = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6086 b->pos = (u_char *) "foo";
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6087 b->last = b->pos + 3;
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 *ll = tl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6090 ll = &tl->next;
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 /* append the next incoming buffer */
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 tl = ngx_alloc_chain_link(r->pool);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6095 if (tl == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6096 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6097 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6098
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6099 tl->buf = cl->buf;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6100 *ll = tl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6101 ll = &tl->next;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6102 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6103
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6104 *ll = NULL;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6105
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6106 /* send the new chain */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6107
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6108 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	6109
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6110 /* update "busy" and "free" chains for reuse */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6111
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6112 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	6113 (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	6114
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6115 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6116 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6117 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6118
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6119 </section>
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
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6122 <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	6123
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6124 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6125 The
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6126 <link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6127 provides basic functionality to pass requests to remote servers.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6128 This functionality is used by modules that implement specific protocols,
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6129 such as HTTP or FastCGI.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6130 The module also provides an interface for creating custom
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6131 load balancing modules and implements a default round-robin balancing method.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6132 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6133
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6134 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6135 Examples of modules that implement alternative load balancing methods are
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6136 <link doc="../http/ngx_http_upstream_module.xml" id="least_conn"/>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6137 and <link doc="../http/ngx_http_upstream_module.xml" id="hash"/>.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6138 Note that these modules are actually implemented as extensions of the upstream
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6139 module and share a lot of code, such as representation of a server group.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6140 The <link doc="../http/ngx_http_upstream_module.xml" id="keepalive"/> module
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6141 is an example of an independent module, extending upstream functionality.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6142 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6143
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6144 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6145 The
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6146 <link doc="../http/ngx_http_upstream_module.xml">ngx_http_upstream_module</link>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6147 may be configured explicitly by placing the corresponding
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6148 <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	6149 the configuration file, or implicitly by using directives
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6150 that accept a URL evaluated at some point to the list of servers,
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6151 for example,
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6152 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/>.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6153 Only explicit configurations may use an alternative load balancing method.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6154 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	6155 <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	6156 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	6157 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6158 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	6159 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	6160 void **srv_conf;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6161
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6162 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	6163
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6164 ngx_uint_t flags;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6165 ngx_str_t host;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6166 u_char *file_name;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6167 ngx_uint_t line;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6168 in_port_t port;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6169 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	6170
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6171 #if (NGX_HTTP_UPSTREAM_ZONE)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6172 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	6173 #endif
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6174 };
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6175 </programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6176
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6177 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6178
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6179 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6180 <literal>srv_conf</literal> — configuration context of upstream modules
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6181 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6182
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6183 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6184 <literal>servers</literal> — array of
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6185 <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	6186 <link doc="../http/ngx_http_upstream_module.xml" id="server"/> directives
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6187 in the <literal>upstream</literal> block
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6188 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6189
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6190 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6191 <literal>flags</literal> — flags that mostly mark which features
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6192 (configured as parameters of
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6193 the <link doc="../http/ngx_http_upstream_module.xml" id="server"/> directive)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6194 are supported by the particular load balancing method.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6195
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6196 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6197
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6198 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6199 <literal>NGX_HTTP_UPSTREAM_CREATE</literal> — used to distinguish explicitly
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6200 defined upstreams from automatically created by
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6201 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_pass"/> and “friends”
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6202 (FastCGI, SCGI, etc.)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6203 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6204
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6205 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6206 <literal>NGX_HTTP_UPSTREAM_WEIGHT</literal> — “<literal>weight</literal>”
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6207 is supported
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6208 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6209
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6210 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6211 <literal>NGX_HTTP_UPSTREAM_MAX_FAILS</literal> — “<literal>max_fails</literal>”
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6212 is supported
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6213 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6214
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6215 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6216 <literal>NGX_HTTP_UPSTREAM_FAIL_TIMEOUT</literal> —
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6217 “<literal>fail_timeout</literal>” is supported
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6218 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6219
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6220 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6221 <literal>NGX_HTTP_UPSTREAM_DOWN</literal> — “<literal>down</literal>”
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6222 is supported
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6223 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6224
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6225 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6226 <literal>NGX_HTTP_UPSTREAM_BACKUP</literal> — “<literal>backup</literal>”
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6227 is supported
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6228 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6229
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6230 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6231 <literal>NGX_HTTP_UPSTREAM_MAX_CONNS</literal> — “<literal>max_conns</literal>”
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6232 is supported
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6233 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6234
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6235 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6236
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6237 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6238
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6239 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6240 <literal>host</literal> — the name of an upstream
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6241 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6242
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6243 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6244 <literal>file_name, line</literal> — the name of the configuration file
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6245 and the line where the <literal>upstream</literal> block is located
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6246 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6247
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6248 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6249 <literal>port</literal> and <literal>no_port</literal> — unused by explicit
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6250 upstreams
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6251 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6252
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6253 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6254 <literal>shm_zone</literal> — a shared memory zone used by this upstream, if any
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6255 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6256
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6257 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6258 <literal>peer</literal> — an object that holds generic methods for
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6259 initializing upstream configuration:
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6260
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6261 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6262 typedef struct {
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6263 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	6264 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	6265 void *data;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6266 } ngx_http_upstream_peer_t;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6267 </programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6268 A module that implements a load balancing algorithm must set these
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6269 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	6270 If <literal>init_upstream</literal> was not initialized during configuration
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6271 parsing, <literal>ngx_http_upstream_module</literal> sets it to default
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6272 <literal>ngx_http_upstream_init_round_robin</literal>.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6273
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6274 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6275 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6276 <literal>init_upstream(cf, us)</literal> — configuration-time
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6277 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	6278 initializing the <literal>init()</literal> method in case of success.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6279 A typical load balancing module uses a list of servers in the upstream block
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6280 to create some efficient data structure that it uses and saves own
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6281 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	6282 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6283
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6284 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6285 <literal>init(r, us)</literal> — initializes per-request
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6286 <literal>ngx_http_upstream_peer_t.peer</literal> (not to be confused with the
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6287 <literal>ngx_http_upstream_srv_conf_t.peer</literal> described above which
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6288 is per-upstream) structure that is used for load balancing.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6289 It will be passed as <literal>data</literal> argument to all callbacks that
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6290 deal with server selection.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6291 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6292 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6293
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6294 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6295 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6296 </para>
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 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6299 When nginx has to pass a request to another host for processing, it uses
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6300 a configured load balancing method to obtain an address to connect to.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6301 The method is taken from the
1994 effdf0747a05 Development guide: fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1993 diff changeset	6302 <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	6303 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	6304 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6305 struct ngx_peer_connection_s {
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6306 [...]
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6307
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6308 struct sockaddr *sockaddr;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6309 socklen_t socklen;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6310 ngx_str_t *name;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6311
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6312 ngx_uint_t tries;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6313
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6314 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	6315 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	6316 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	6317 void *data;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6318
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6319 #if (NGX_SSL \|\| NGX_COMPAT)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6320 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	6321 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	6322 #endif
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 [..]
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 </programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6327
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6328 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	6329
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6330 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6331 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6332 <literal>sockaddr</literal>, <literal>socklen</literal>,
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6333 <literal>name</literal> — address of an upstream server to connect to;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6334 this is the output parameter of a load balancing method
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6335 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6336
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6337 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6338 <literal>data</literal> — per-request load balancing method data; keeps the
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6339 state of selection algorithm and usually includes the link to upstream
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6340 configuration.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6341 It will be passed as an argument to all methods that deal with server selection
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6342 (see below)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6343 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6344
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6345 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6346 <literal>tries</literal> — allowed
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6347 <link doc="../http/ngx_http_proxy_module.xml" id="proxy_next_upstream_tries">number</link>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6348 of attempts to connect to an upstream.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6349 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6350
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6351 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6352 <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	6353 <literal>set_session</literal>, and <literal>save_session</literal>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6354 - methods of the load balancing module, see description below
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6355 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6356
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6357 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6358
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6359 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6360
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6361 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6362 All methods accept at least two arguments: peer connection object
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6363 <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	6364 <literal>ngx_http_upstream_srv_conf_t.peer.init()</literal>.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6365 Note that in general case it may differ from <literal>pc.data</literal> due
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6366 to “chaining” of load balancing modules.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6367 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6368
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6369 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6370
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6371 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6372 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6373 <literal>get(pc, data)</literal> — the method is called when the upstream
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6374 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	6375 its address.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6376 The method is responsible to fill in the <literal>sockaddr</literal>,
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6377 <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	6378 <literal>ngx_peer_connection_t</literal> structure.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6379 The return value may be one of:
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6380
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6381 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6382
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6383 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6384 <literal>NGX_OK</literal> — server was selected
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6385 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6386
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6387 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6388 <literal>NGX_ERROR</literal> — internal error occurred
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6389 </listitem>
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 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6392 <literal>NGX_BUSY</literal> — there are no available servers at the moment.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6393 This can happen due to many reasons, such as: dynamic server group is empty,
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6394 all servers in the group are in the failed state,
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6395 all servers in the group are already
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6396 handling the maximum number of connections or similar.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6397 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6398
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6399 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6400 <literal>NGX_DONE</literal> — this is set by the <literal>keepalive</literal>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6401 module to indicate that the underlying connection was reused and there is no
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6402 need to create a new connection to the upstream server.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6403 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6404
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6405 <!--
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6406 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6407 <literal>NGX_ABORT</literal> — this is set by the <literal>queue</literal>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6408 module to indicate that the request was queued and the further processing
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6409 of this request should be postponed.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6410 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6411 -->
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6412
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6413 </list>
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>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6416
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6417 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6418 <literal>free(pc, data, state)</literal> — the method is called when an
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6419 upstream module has finished work with a particular server.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6420 The <literal>state</literal> argument is the status of upstream connection
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6421 completion.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6422 This is a bitmask, the following values may be set:
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6423 <literal>NGX_PEER_FAILED</literal> — this attempt is considered
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6424 <link doc="../http/ngx_http_upstream_module.xml" id="max_fails">unsuccessful</link>,
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6425 <literal>NGX_PEER_NEXT</literal> — a special case with codes 403 and 404
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6426 (see link above), which are not considered a failure.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6427 <literal>NGX_PEER_KEEPALIVE</literal>.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6428 Also, <literal>tries</literal> counter is decremented by this method.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6429 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6430
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6431 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6432 <literal>notify(pc, data, type)</literal> — currently unused
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6433 in the OSS version.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6434 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6435
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6436 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6437 <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	6438 <literal>save_session(pc, data)</literal>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6439 — SSL-specific methods that allow to cache sessions to upstream
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6440 servers.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6441 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	6442 </listitem>
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 </list>
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 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6447
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6448 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6449
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6450 </section>
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6451
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	6452 </article>

Mercurial > hg > nginx-site

annotate xml/en/docs/dev/development_guide.xml @ 1998:18404f5a5600