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

annotate xml/en/docs/dev/development_guide.xml @ 1993:98b713b0a9fa

Language and style fixes in development guide.

author	Roman Arutyunyan <arut@nginx.com>
date	Tue, 30 May 2017 14:30:04 +0300
parents	7660d6390a9d
children	effdf0747a05

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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	400 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	401
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	402
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	403 <section name="Formatting" id="formatting">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	404
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	405 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	406 The following formatting functions support nginx-specific types:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	407 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	408
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	409
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	410 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	411 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	412
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	413 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	414 <literal>ngx_sprintf(buf, fmt, ...)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	415 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	416
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	417 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	418 <literal>ngx_snprintf(buf, max, fmt, ...)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	419 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	420
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	421 <listitem>
1975 459a6f194fcf Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1971 diff changeset	422 <literal>ngx_slprintf(buf, last, fmt, ...)</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	423 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	424
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	425 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	426 <literal>ngx_vslprint(buf, last, fmt, args)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	427 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	428
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	429 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	430 <literal>ngx_vsnprint(buf, max, fmt, args)</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	431 </listitem>
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 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	434 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	435
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	436 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	437 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	438 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	439 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	440
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	441
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	442 <list type="bullet">
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	443
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	444 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	445 <literal>%O</literal> — <literal>off_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	446 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	447
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	448 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	449 <literal>%T</literal> — <literal>time_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	450 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	451
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	452 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	453 <literal>%z</literal> — <literal>size_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	454 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	455
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	456 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	457 <literal>%i</literal> — <literal>ngx_int_t_t</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	458 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	459
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	460 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	461 <literal>%p</literal> — <literal>void *</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	462 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	463
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	464 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	465 <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	466 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	467
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	468 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	469 <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	470 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	471
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	472 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	473 <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	474 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	475
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	476 </list>
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	479 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	480 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	481 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	482 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	483
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	484 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	485 For example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	486
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	487 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	488 u_char buf[NGX_INT_T_LEN];
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	489 size_t len;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	490 ngx_int_t n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	491
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	492 /* set n here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	493
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	494 len = ngx_sprintf(buf, "%ui", n) — buf;
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	495 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	496
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	497 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	498
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	499 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	500
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	501
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	502 <section name="Numeric conversion" id="numeric_conversion">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	503
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	504 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	505 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	506 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	507 the indicated type.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	508 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	509
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	510 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	511
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	512 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	513 <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	514 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	515
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	516 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	517 <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	518 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	519
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	520 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	521 <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	522 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	523
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	524 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	525 <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	526 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	527
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	528 </list>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	529 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	530
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	531 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	532 There are two additional numeric conversion functions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	533 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	534
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	535 <list type="bullet">
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	536
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	537 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	538 <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	539 number of given length to a positive integer of type
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	540 <literal>ngx_int_t</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	541 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	542 positions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	543 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	544 than <literal>points</literal> fractional digits.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	545 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	546 <literal>1050</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	547 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	548
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	549 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	550 <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	551 of a positive integer to <literal>ngx_int_t</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	552 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	553
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	554 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	555 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	556
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	557 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	558
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	559 <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	560
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	561 <para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	562 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	563 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	564 library.
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	565 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	566 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	567
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	568 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	569 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	570 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	571 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	572 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	573
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	574 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	575 #if (NGX_PCRE)
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	576 ngx_regex_t *re;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	577 ngx_regex_compile_t rc;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	578
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	579 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	580
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	581 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	582
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	583 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	584
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	585 rc.pattern = value;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	586 rc.pool = cf->pool;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	587 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	588 rc.err.data = errstr;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	589 /* 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	590
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	591 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	592 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	593 return NGX_CONF_ERROR;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	594 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	595
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	596 re = rc.regex;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	597 #endif
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	598 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	599 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	600 <literal>named_captures</literal> fields in the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	601 <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	602 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	603 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	604
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	605 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	606 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	607 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	608 ngx_int_t n;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	609 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	610
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	611 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	612
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	613 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	614 if (n >= 0) {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	615 /* string matches expression */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	616
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	617 } 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	618 /* no match was found */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	619
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	620 } else {
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	621 /* some error */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	622 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	623 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	624 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	625 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	626 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	627 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	628 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	629 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	630 as required by the
1919 dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	631 <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	632 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	633 <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	634 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	635
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	636 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	637 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	638 <programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	639 u_char *p;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	640 size_t size;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	641 ngx_str_t name, value;
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 /* all captures */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	644 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	645 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	646 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	647 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	648
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	649 /* accessing named captures */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	650
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	651 size = rc.name_size;
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	652 p = rc.names;
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 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	655
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	656 /* capture name */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	657 name.data = &p[2];
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	658 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	659
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	660 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	661
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	662 /* captured value */
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	663 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	664 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	665 }
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	666 </programlisting>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	667 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	668
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	669 <para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	670 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	671 <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	672 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	673 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	674 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	675 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	676 <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	677 in case of error.
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	678 </para>
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	679
dcfb4f3ac8a7 Added the "Regular expressions" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1915 diff changeset	680 </section>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	681
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	682 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	683
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	684
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	685 <section name="Time" id="time">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	686
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	687 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	688 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	689 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	690 <programlisting>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	691 typedef struct {
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	692 time_t sec;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	693 ngx_uint_t msec;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	694 ngx_int_t gmtoff;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	695 } ngx_time_t;
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	696 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	697 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	698 <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	699 on Windows.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	700 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	701
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	702 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	703 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	704 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	705 format.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	706 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	707 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	708 <literal>ngx_msec_t</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	709 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	710
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	711 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	712 The available string representations are:
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	713
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	714 <list type="bullet">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	715
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	716 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	717 <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	718 <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	719 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	720
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	721 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	722 <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	723 <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	724 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	725
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	726 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	727 <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	728 <literal>"Sep 28 12:00:00"</literal>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	729 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	730
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	731 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	732 <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	733 <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	734 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	735
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	736 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	737 <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	738 standard format:
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	739 <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	740 </listitem>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	741
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	742 </list>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	743 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	744
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	745 <para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	746 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	747 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	748 the cached time value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	749 </para>
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 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	752 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	753 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	754 <literal>struct timeval</literal>).
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	755 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	756 calls.
1982 28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	757 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	758 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	759 signal handler context.
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	760 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	761
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	762 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	763 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	764 broken-down time representation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	765 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	766 <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	767 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	768
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	769 <list type="bullet">
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	770
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	771 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	772 <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	773 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	774
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	775 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	776 <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	777 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	778 </listitem>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	779
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	780 </list>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	781
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	782 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	783 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	784 <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	785 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	786 representation function returns a string representation suitable
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	787 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	788 </para>
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	789
28ee7ab54a90 Added the "Time" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1981 diff changeset	790 </section>
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
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	793 <section name="Containers" id="containers">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	794
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	795
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	796 <section name="Array" id="array">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	797
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	798 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	799 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	800 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	801
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	802
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	803 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	804 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	805 void *elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	806 ngx_uint_t nelts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	807 size_t size;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	808 ngx_uint_t nalloc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	809 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	810 } ngx_array_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	811 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	812
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	813 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	814 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	815 The <literal>nelts</literal> field holds the number of elements.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	816 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	817 when the array is initialized.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	818 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	819
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	820 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	821 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	822 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	823 call to initialize an array object that has already been allocated.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	824 </para>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	827 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	828 ngx_array_t *a, b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	829
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	830 /* create an array of strings with preallocated memory for 10 elements */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	831 a = ngx_array_create(pool, 10, sizeof(ngx_str_t));
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 /* initialize string array for 10 elements */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	834 ngx_array_init(&b, pool, 10, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	835 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	836
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	837 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	838 Use the following functions to add elements to an array:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	839 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	840
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	841 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	842 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	843
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	844 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	845 <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	846 to it
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	847 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	848
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	849 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	850 <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	851 and returns pointer to the first one
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	852 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	853
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	854 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	855 </para>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	858 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	859 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	860 are copied to it.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	861 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	862 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	863
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	864
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 s = ngx_array_push(a);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	867 ss = ngx_array_push_n(&b, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	868 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	869
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	870 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	871
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	872
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	873 <section name="List" id="list">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	874
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	875 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	876 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	877 large number of items.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	878 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	879 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	880
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	881
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	882 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	883 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	884 ngx_list_part_t *last;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	885 ngx_list_part_t part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	886 size_t size;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	887 ngx_uint_t nalloc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	888 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	889 } ngx_list_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	890 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	891
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	892 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	893 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	894 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	895
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	896
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	897 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	898 typedef struct ngx_list_part_s ngx_list_part_t;
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 struct ngx_list_part_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	901 void *elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	902 ngx_uint_t nelts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	903 ngx_list_part_t *next;
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 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	906
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	907 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	908 Before use, a list must be initialized by calling
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	909 <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	910 <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	911 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	912 items per list part.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	913 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	914 function.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	915 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	916 example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	917 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	918
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	919
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 ngx_str_t *v;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	922 ngx_uint_t i;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	923 ngx_list_t *list;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	924 ngx_list_part_t *part;
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 list = ngx_list_create(pool, 100, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	927 if (list == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	928
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	929 /* add items to the list */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	930
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	931 v = ngx_list_push(list);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	932 if (v == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	933 ngx_str_set(v, "foo");
1899 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 v = ngx_list_push(list);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	936 if (v == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	937 ngx_str_set(v, "bar");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	938
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	939 /* iterate over the list */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	940
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	941 part = &list->part;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	942 v = part->elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	943
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	944 for (i = 0; /* void */; i++) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	945
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	946 if (i >= part->nelts) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	947 if (part->next == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	948 break;
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	951 part = part->next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	952 v = part->elts;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	953 i = 0;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	954 }
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 ngx_do_smth(&v[i]);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	957 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	958 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	959
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	960 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	961 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	962 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	963
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	964 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	965 Lists do not support item removal.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	966 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	967 being removed from the list.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	968 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	969 <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	970 <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	971 zero.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	972 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	973 over.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	974 </para>
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 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	977
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	978
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	979 <section name="Queue" id="queue">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	982 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	983 follows:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	984 </para>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	987 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	988 typedef struct ngx_queue_s ngx_queue_t;
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 struct ngx_queue_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	991 ngx_queue_t *prev;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	992 ngx_queue_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	993 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	994 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	995
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	996 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	997 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	998 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	999 before use.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1000 Queues support the following operations:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1001 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1002
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1003 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1004 <list type="bullet">
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 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1007 <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	1008 <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	1009 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1010
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1011 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1012 <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	1013 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1014
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1015 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1016 <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	1017 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	1018 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1019
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1020 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1021 <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	1022 </listitem>
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 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1025 <literal>ngx_queue_head(h)</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1026 <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	1027 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1028
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1029 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1030 <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	1031 iteration at
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1032 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1033
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1034 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1035 <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	1036 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	1037 it
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1038 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1039
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1040 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1041 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1042
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1043 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1044 An example:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1045 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1046
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1047
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1048 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1049 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1050 ngx_str_t value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1051 ngx_queue_t queue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1052 } ngx_foo_t;
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 ngx_foo_t *f;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1055 ngx_queue_t values;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1056
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1057 ngx_queue_init(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1058
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1059 f = ngx_palloc(pool, sizeof(ngx_foo_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1060 if (f == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1061 ngx_str_set(&f->value, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1062
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1063 ngx_queue_insert_tail(&values, f);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1064
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1065 /* insert more nodes here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1066
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1067 for (q = ngx_queue_head(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1068 q != ngx_queue_sentinel(&values);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1069 q = ngx_queue_next(q))
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1070 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1071 f = ngx_queue_data(q, ngx_foo_t, queue);
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 ngx_do_smth(&f->value);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1074 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1075 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1076
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1077 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1078
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1079
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1080 <section name="Red-Black tree" id="red_black_tree">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1081
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1082 <para>
1915 8b7c3b0ef1a4 Semantically marked paths. Vladimir Homutov <vl@nginx.com> parents: 1914 diff changeset	1083 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	1084 effective implementation of red-black trees.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1085 </para>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1088 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1089 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1090 ngx_rbtree_t rbtree;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1091 ngx_rbtree_node_t sentinel;
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 /* custom per-tree data here */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1094 } my_tree_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1095
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1096 typedef struct {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1097 ngx_rbtree_node_t rbnode;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1098
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1099 /* custom per-node data */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1100 foo_t val;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1101 } my_node_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1102 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1103
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1104 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1105 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	1106 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	1107 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	1108 your data.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1109 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1110
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1111 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1112 To initialize a tree:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1113 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1114
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1115
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1116 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1117 my_tree_t root;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1118
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1119 ngx_rbtree_init(&root.rbtree, &root.sentinel, insert_value_function);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1120 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1121
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1122 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1123 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	1124 "<literal>insert_value</literal>" functions.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1125 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	1126 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	1127 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	1128 node to be added, and a tree sentinel.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1129 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1130
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1131
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 void ngx_str_rbtree_insert_value(ngx_rbtree_node_t *temp,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1134 ngx_rbtree_node_t *node,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1135 ngx_rbtree_node_t *sentinel)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1136 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1137
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1138
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 The traversal is pretty straightforward and can be demonstrated with the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1141 following lookup function pattern:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1142 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1143
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 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1146 my_node_t *
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1147 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	1148 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1149 ngx_int_t rc;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1150 my_node_t *n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1151 ngx_rbtree_node_t node, sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1152
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1153 node = rbtree->root;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1154 sentinel = rbtree->sentinel;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1155
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1156 while (node != sentinel) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1157
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1158 n = (my_node_t *) node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1159
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1160 if (hash != node->key) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1161 node = (hash < node->key) ? node->left : node->right;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1162 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1163 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1164
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1165 rc = compare(val, node->val);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1166
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1167 if (rc < 0) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1168 node = node->left;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1169 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1170 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1171
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1172 if (rc > 0) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1173 node = node->right;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1174 continue;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1175 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1176
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1177 return n;
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1180 return NULL;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1181 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1182 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1183
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1184 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1185 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	1186 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	1187 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	1188 hash field is used.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1189 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1190
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1191 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1192 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	1193 <literal>ngx_rbtree_insert()</literal>:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1194 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1195
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 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1198 my_node_t *my_node;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1199 ngx_rbtree_node_t *node;
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 my_node = ngx_palloc(...);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1202 init_custom_data(&my_node->val);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1203
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1204 node = &my_node->rbnode;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1205 node->key = create_key(my_node->val);
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 ngx_rbtree_insert(&root->rbtree, node);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1208 </programlisting>
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1211 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	1212 </para>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1215 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1216 ngx_rbtree_delete(&root->rbtree, node);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1217 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1218
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1219 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1220
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1221 <section name="Hash" id="hash">
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1222
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1223 <para>
1920 de5251816480 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1919 diff changeset	1224 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	1225 Both exact and wildcard matching are supported.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1226 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	1227 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1228
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1229 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1230 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	1231 hold so that nginx can build it optimally.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1232 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	1233 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	1234 <link doc="../hash.xml">document</link>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1235 They are usually configurable by the user.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1236 Hash initialization settings are stored with the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1237 <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	1238 <literal>ngx_hash_t</literal>:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1239 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1240 ngx_hash_t foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1241 ngx_hash_init_t hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1242
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1243 hash.hash = &foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1244 hash.key = ngx_hash_key;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1245 hash.max_size = 512;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1246 hash.bucket_size = ngx_align(64, ngx_cacheline_size);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1247 hash.name = "foo_hash";
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1248 hash.pool = cf->pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1249 hash.temp_pool = cf->temp_pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1250 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1251 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	1252 integer key from a string.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1253 There are two generic key-creation functions:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1254 <literal>ngx_hash_key(data, len)</literal> and
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1255 <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	1256 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	1257 must be writeable.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1258 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	1259 to the function, initializing the key array (see below).
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1260 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1261
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1262 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1263 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	1264 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	1265 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	1266 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	1267 <literal>NGX_HASH_LARGE</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1268 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	1269 elements.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1270
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1271 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1272 ngx_hash_keys_arrays_t foo_keys;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1273
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1274 foo_keys.pool = cf->pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1275 foo_keys.temp_pool = cf->temp_pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1276
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1277 ngx_hash_keys_array_init(&foo_keys, NGX_HASH_SMALL);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1278 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1279 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1280
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1281 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1282 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	1283 <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	1284 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1285 ngx_str_t k1 = ngx_string("key1");
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1286 ngx_str_t k2 = ngx_string("key2");
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1287
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1288 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	1289 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	1290 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1291 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1292
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1293 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1294 To build the hash table, call the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1295 <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	1296
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1297 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1298 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	1299 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1300
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1301 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	1302 <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	1303 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1304
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1305 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1306 When the hash is built, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1307 <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	1308 elements:
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1309 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1310 my_data_t *data;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1311 ngx_uint_t key;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1312
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1313 key = ngx_hash_key(k1.data, k1.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1314
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1315 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	1316 if (data == NULL) {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1317 /* key not found */
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1318 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1319 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1320
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 <section name="Wildcard matching" id="wildcard_matching">
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1324
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1325 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1326 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	1327 <literal>ngx_hash_combined_t</literal> type.
1914 f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1328 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	1329 <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	1330 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	1331 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1332 ngx_hash_init_t hash
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1333 ngx_hash_combined_t foo_hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1334
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1335 hash.hash = &foo_hash.hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1336 hash.key = ...;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1337 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1338 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1339
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1340 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1341 It is possible to add wildcard keys using the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1342 <literal>NGX_HASH_WILDCARD_KEY</literal> flag:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1343 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1344 /* k1 = ".example.org"; */
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1345 /* k2 = "foo."; /
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1346 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	1347 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	1348 </programlisting>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1349 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	1350 Please refer to the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1351 <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	1352 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	1353 matching algorithm.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1354 </para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1355
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1356 <para>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1357 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	1358 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	1359 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	1360 <programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1361 if (foo_keys.dns_wc_head.nelts) {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1362
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1363 ngx_qsort(foo_keys.dns_wc_head.elts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1364 (size_t) foo_keys.dns_wc_head.nelts,
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1365 sizeof(ngx_hash_key_t),
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1366 cmp_dns_wildcards);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1367
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1368 hash.hash = NULL;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1369 hash.temp_pool = pool;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1370
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1371 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	1372 foo_keys.dns_wc_head.nelts)
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1373 != NGX_OK)
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1374 {
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1375 return NGX_ERROR;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1376 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1377
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1378 foo_hash.wc_head = (ngx_hash_wildcard_t *) hash.hash;
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1379 }
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1380 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1381 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	1382 to the combined hash.
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1383 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	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 The lookup in a combined hash is handled by the
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1388 <literal>ngx_hash_find_combined(chash, key, name, len)</literal>:
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1389 <programlisting>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	1390 /* 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	1391 /* key = "foo.example.com"; — will match "foo." /
1914 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 hkey = ngx_hash_key(key.data, key.len);
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1394 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	1395 </programlisting>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1396 </para>
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 </section>
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1399
f8659301a260 Added hash API description. Vladimir Homutov <vl@nginx.com> parents: 1907 diff changeset	1400 </section>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1401
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1402 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1403
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1404
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1405 <section name="Memory management" id="memory_management">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1406
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1407
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1408 <section name="Heap" id="heap">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1409
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1410 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1411 To allocate memory from system heap, use the following functions:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1412 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1413
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1414 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1415 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1416
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1417 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1418 <literal>ngx_alloc(size, log)</literal> — Allocate memory from system heap.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1419 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	1420 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	1421 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1422
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1423 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1424 <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	1425 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	1426 allocation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1427 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1428
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1429 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1430 <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	1431 from system heap.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1432 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	1433 on those platforms that provide that function.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1434 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	1435 provides maximum alignment.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1436 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1437
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1438 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1439 <literal>ngx_free(p)</literal> — Free allocated memory.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1440 This is a wrapper around <literal>free()</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1441 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1442
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1443 </list>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1446 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1447
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1448
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1449 <section name="Pool" id="pool">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1450
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1451 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1452 Most nginx allocations are done in pools.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1453 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	1454 destroyed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1455 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	1456 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1457
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1458 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1459 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	1460 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	1461 block list.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1462 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	1463 is forwarded to the system allocator and the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1464 returned pointer is stored in the pool for further deallocation.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1465 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1466
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1467 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1468 The type for nginx pools is <literal>ngx_pool_t</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1469 The following operations are supported:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1470 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1471
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1472 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1473 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1474
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1475 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1476 <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	1477 block size.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1478 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	1479 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1480
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1481 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1482 <literal>ngx_destroy_pool(pool)</literal> — Free all pool memory, including
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1483 the pool object itself.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1484 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1485
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1486 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1487 <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	1488 specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1489 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1490
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1491 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1492 <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	1493 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	1494 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1495
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1496 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1497 <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	1498 specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1499 Mostly used for allocating strings.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1500 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1501
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1502 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1503 <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	1504 allocated in the specified pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1505 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	1506 can be freed.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1507 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1508
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1509 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1510 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1511
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1512 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1513 u_char *p;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1514 ngx_str_t *s;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1515 ngx_pool_t *pool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1516
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1517 pool = ngx_create_pool(1024, log);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1518 if (pool == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1519
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1520 s = ngx_palloc(pool, sizeof(ngx_str_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1521 if (s == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1522 ngx_str_set(s, "foo");
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1523
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1524 p = ngx_pnalloc(pool, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1525 if (p == NULL) { /* error */ }
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1526 ngx_memcpy(p, "foo", 3);
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1527 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1528
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1529 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1530 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	1531 so the nginx pool implementation provides a way to reuse them.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1532 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	1533 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	1534 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	1535 <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	1536 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	1537 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	1538 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	1539 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1540
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1541 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1542 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	1543 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	1544 destroyed.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1545 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	1546 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	1547 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	1548 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	1549 the main object.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1550 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1551
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1552 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1553 To register a pool cleanup, call
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1554 <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	1555 <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	1556 be filled in by the caller.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1557 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	1558 handler.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1559 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1560
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1561
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1562 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1563 ngx_pool_cleanup_t *cln;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1564
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1565 cln = ngx_pool_cleanup_add(pool, 0);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1566 if (cln == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1567
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1568 cln->handler = ngx_my_cleanup;
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	1569 cln->data = "foo";
1899 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 ...
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1572
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1573 static void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1574 ngx_my_cleanup(void *data)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1575 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1576 u_char *msg = data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1577
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1578 ngx_do_smth(msg);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1579 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1580 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1581
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1582 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1583
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1584
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1585 <section name="Shared memory" id="shared_memory">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1586
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1587 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1588 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	1589 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	1590 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	1591 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	1592 of the zone.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1593 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	1594 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	1595 <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	1596 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	1597 different tag.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1598 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	1599 <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	1600 one nginx module.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1601 </para>
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1604 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	1605 following fields:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1606 </para>
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1609 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1610
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1611 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1612 <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	1613 is mapped to actual memory
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1614 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1615
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1616 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1617 <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	1618 <literal>init</literal> callback
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1619 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1620
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1621 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1622 <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	1623 old cycle
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1624 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1625
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1626 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1627 <literal>tag</literal> — Shared zone tag
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1628 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1629
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1630 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1631 <literal>shm</literal> — Platform-specific object of type
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1632 <literal>ngx_shm_t</literal>, having at least the following fields:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1633 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1634
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1635 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1636 <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	1637 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1638
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1639 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1640 <literal>size</literal> — Shared memory size
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1641 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1642
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1643 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1644 <literal>name</literal> — Shared memory name
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1645 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1646
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1647 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1648 <literal>log</literal> — Shared memory log
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1649 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1650
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1651 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1652 <literal>exists</literal> — Flag that indicates shared memory was inherited
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1653 from the master process (Windows-specific)
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 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1657 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1658
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1659 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1660 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1661
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1662 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1663 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	1664 <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	1665 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	1666 shared anonymous mapping.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1667 On Windows, the <literal>CreateFileMapping()</literal>/
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1668 <literal>MapViewOfFileEx()</literal> pair is used.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1669 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1670
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1671 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1672 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	1673 <literal>ngx_slab_pool_t</literal> type.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1674 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	1675 zone.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1676 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	1677 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	1678 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	1679 <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	1680 <literal>ngx_slab_calloc(pool, size)</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1681 To free memory, call <literal>ngx_slab_free(pool, p)</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1682 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1683
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1684 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1685 Slab pool divides all shared zone into pages.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1686 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	1687 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	1688 8 bytes.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1689 Nonconforming values are rounded up.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1690 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	1691 allocation.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1692 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	1693 done an entire page at a time
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1694 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1695
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1696 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1697 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	1698 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	1699 <literal>ngx_slab_pool_t</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1700 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	1701 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	1702 in the shared zone.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1703 To lock or unlock a mutex, call
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1704 <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	1705 <literal>ngx_shmtx_unlock(&shpool->mutex)</literal> respectively.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1706 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1707
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1708
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1709 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1710 ngx_str_t name;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1711 ngx_foo_ctx_t *ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1712 ngx_shm_zone_t *shm_zone;
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 ngx_str_set(&name, "foo");
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1715
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1716 /* allocate shared zone context */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1717 ctx = ngx_pcalloc(cf->pool, sizeof(ngx_foo_ctx_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1718 if (ctx == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1719 /* error */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1720 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1721
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1722 /* add an entry for 64k shared zone */
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1723 shm_zone = ngx_shared_memory_add(cf, &name, 65536, &ngx_foo_module);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1724 if (shm_zone == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1725 /* error */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1726 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1727
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1728 /* register init callback and context */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1729 shm_zone->init = ngx_foo_init_zone;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1730 shm_zone->data = ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1731
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1732
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1733 ...
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1734
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1735
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1736 static ngx_int_t
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1737 ngx_foo_init_zone(ngx_shm_zone_t shm_zone, void data)
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 ngx_foo_ctx_t *octx = data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1740
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1741 size_t len;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1742 ngx_foo_ctx_t *ctx;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1743 ngx_slab_pool_t *shpool;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1744
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1745 value = shm_zone->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1746
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1747 if (octx) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1748 /* reusing a shared zone from old cycle */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1749 ctx->value = octx->value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1750 return NGX_OK;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1751 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1752
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1753 shpool = (ngx_slab_pool_t *) shm_zone->shm.addr;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1754
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1755 if (shm_zone->shm.exists) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1756 /* initialize shared zone context in Windows nginx worker */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1757 ctx->value = shpool->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1758 return NGX_OK;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1759 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1760
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1761 /* initialize shared zone */
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 ctx->value = ngx_slab_alloc(shpool, sizeof(ngx_uint_t));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1764 if (ctx->value == NULL) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1765 return NGX_ERROR;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1766 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1767
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1768 shpool->data = ctx->value;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1769
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1770 return NGX_OK;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1771 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1772 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1773
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1774 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1775
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 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1778
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1779
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1780 <section name="Logging" id="logging">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1783 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	1784 The nginx logger supports several types of output:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1785
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1786 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1787
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1788 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1789 stderr — Logging to standard error (stderr)
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1790 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1791
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1792 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1793 file — Logging to a file
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1794 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1795
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1796 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1797 syslog — Logging to syslog
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1798 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1799
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1800 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1801 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	1802 can be accessed later with a debugger
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1803 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1804
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1805 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1806 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1807
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1808 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1809 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	1810 the <literal>next</literal> field.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1811 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	1812 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1813
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1814 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1815 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	1816 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	1817 The following severity levels are supported:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1818 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1819
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1820 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1821 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1822
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1823 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1824 <literal>NGX_LOG_EMERG</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1825 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1826
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1827 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1828 <literal>NGX_LOG_ALERT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1829 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1830
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1831 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1832 <literal>NGX_LOG_CRIT</literal>
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 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1836 <literal>NGX_LOG_ERR</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1837 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1838
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1839 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1840 <literal>NGX_LOG_WARN</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1841 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1842
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1843 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1844 <literal>NGX_LOG_NOTICE</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1845 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1846
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1847 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1848 <literal>NGX_LOG_INFO</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1849 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1850
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1851 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1852 <literal>NGX_LOG_DEBUG</literal>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1855 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1856 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1857
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1858 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1859 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	1860 The debug masks are:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1861 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1862
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1863 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1864 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1865
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1866 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1867 <literal>NGX_LOG_DEBUG_CORE</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1868 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1869
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1870 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1871 <literal>NGX_LOG_DEBUG_ALLOC</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1872 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1873
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1874 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1875 <literal>NGX_LOG_DEBUG_MUTEX</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1876 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1877
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1878 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1879 <literal>NGX_LOG_DEBUG_EVENT</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1880 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1881
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1882 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1883 <literal>NGX_LOG_DEBUG_HTTP</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1884 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1885
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1886 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1887 <literal>NGX_LOG_DEBUG_MAIL</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1888 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1889
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1890 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1891 <literal>NGX_LOG_DEBUG_STREAM</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1892 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1893
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1894 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1895 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1896
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1897 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1898 Normally, loggers are created by existing nginx code from
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1899 <literal>error_log</literal> directives and are available at nearly every stage
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1900 of processing in cycle, configuration, client connection and other objects.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1901 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1902
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1903 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1904 Nginx provides the following logging macros:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1905 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1906
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1907 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1908 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1909
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1910 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1911 <literal>ngx_log_error(level, log, err, fmt, ...)</literal> — Error logging
1899 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
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 <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	1916 <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	1917 logging with up to eight supported formatting arguments
1899 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 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1921 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1922
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1923 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1924 A log message is formatted in a buffer of size
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1925 <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	1926 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	1927 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	1928 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	1929 prepend more specific information to the log message.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1930 HTTP module sets <literal>ngx_http_log_error()</literal> function as log
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1931 handler to log client and server addresses, current action (stored in
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1932 <literal>log->action</literal>), client request line, server name etc.
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1935 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1936 /* specify what is currently done */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1937 log->action = "sending mp4 to client”;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1938
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1939 /* error and debug log */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1940 ngx_log_error(NGX_LOG_INFO, c->log, 0, "client prematurely
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1941 closed connection”);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1942
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1943 ngx_log_debug2(NGX_LOG_DEBUG_HTTP, mp4->file.log, 0,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1944 "mp4 start:%ui, length:%ui”, mp4->start, mp4->length);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1945 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1946
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1947 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1948 The example above results in log entries like these:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1949 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1950
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1951
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1952 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1953 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	1954 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	1955 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	1956 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1957
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1958 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1959
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1960
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1961 <section name="Cycle" id="cycle">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1962
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1963 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1964 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	1965 configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1966 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	1967 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	1968 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	1969 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	1970 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	1971 successfully created.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1972 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1973
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1974 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1975 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	1976 takes the previous cycle as its argument.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1977 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	1978 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	1979 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	1980 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	1981 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1982
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1983 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1984 Members of the cycle include:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1985 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1986
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1987 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1988 <list type="bullet">
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 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1991 <literal>pool</literal> — Cycle pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1992 Created for each new cycle.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1993 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1994
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1995 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1996 <literal>log</literal> — Cycle log.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	1997 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	1998 <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	1999 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2000
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2001 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2002 <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	2003 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	2004 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2005
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2006 <listitem>
1981 082724c57c38 Fixes in cycle section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1980 diff changeset	2007 <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	2008 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	2009 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	2010 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	2011 sets the number of connections <literal>connection_n</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2012 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2013
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2014 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2015 <literal>free_connections</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2016 <literal>free_connection_n</literal> — List and number of currently available
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2017 connections.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2018 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	2019 or connect to upstream servers.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2020 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2021
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2022 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2023 <literal>files</literal>, <literal>files_n</literal> — Array for mapping file
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2024 descriptors to nginx connections.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2025 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	2026 <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	2027 <literal>poll</literal> and <literal>devpoll</literal>).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2028 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2029
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2030 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2031 <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	2032 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	2033 files.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2034 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2035
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2036 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2037 <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	2038 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	2039 the current configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2040 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2041
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2042 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2043 <literal>listening</literal> — Array of listening objects of type
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2044 <literal>ngx_listening_t</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2045 Listening objects are normally added by the <literal>listen</literal>
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2046 directive of different modules which call the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2047 <literal>ngx_create_listening()</literal> function.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2048 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	2049 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2050
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2051 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2052 <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	2053 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	2054 modules which are going to operate on certain directories.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2055 These directories are created by nginx after reading configuration, if missing.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2056 Moreover, two handlers can be added for each path:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2057
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2058 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2059
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2060 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2061 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	2062 nginx.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2063 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	2064 memory.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2065 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	2066 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2067
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2068 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2069 path manager — Executes periodically.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2070 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	2071 memory to reflect the changes.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2072 The handler is called from the dedicated “nginx cache manager” process.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2073 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2074
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2075 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2076 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2077
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2078 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2079 <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	2080 <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	2081 <literal>ngx_conf_open_file()</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2082 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	2083 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	2084 <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	2085 object's <literal>fd</literal> field.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2086 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	2087 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	2088 reopen signal (most often <literal>USR1</literal>).
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2089 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	2090 new value.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2091 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2092
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2093 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2094 <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	2095 calling the <literal>ngx_shared_memory_add()</literal> function.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2096 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	2097 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	2098 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2099
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2100 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2101 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2102
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2103 </section>
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 <section name="Buffer" id="buffer">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2106
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2107 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2108 For input/output operations, nginx provides the buffer type
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2109 <literal>ngx_buf_t</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2110 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	2111 source.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2112 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	2113 possible for a buffer to reference both at the same time.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2114 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	2115 structure <literal>ngx_buf_t</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2116 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2117
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2118 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2119 The <literal>ngx_buf_t</literal> structure has the following fields:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2120 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2121
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2122 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2123 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2124
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2125 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2126 <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	2127 block allocated for the buffer.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2128 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2129
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2130 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2131 <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	2132 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	2133 <literal>end</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2134 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2135
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2136 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2137 <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	2138 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	2139 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2140
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2141 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2142 <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	2143 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	2144 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2145
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2146 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2147 <literal>file</literal> — File object.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2148 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2149
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2150 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2151 <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	2152 writable memory.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2153 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2154
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2155 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2156 <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	2157 memory.
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>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	2162 in a file.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2163 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2164
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2165 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2166 <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	2167 need to be flushed.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2168 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2169
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2170 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2171 <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	2172 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	2173 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2174
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2175 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2176 <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	2177 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	2178 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	2179 nginx to skip the error check.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2182 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2183 <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	2184 output.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2187 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2188 <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	2189 buffers in a request or subrequest.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2192 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2193 <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	2194 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	2195 shadow.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2196 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	2197 consumed.
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>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	2202 one that references a particular shadow buffer.
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>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	2207 file.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2208 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2209
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2210 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2211 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2212
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2213 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2214 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	2215 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	2216 defined as follows:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2217 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2218
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2219
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2220 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2221 typedef struct ngx_chain_s ngx_chain_t;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2222
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2223 struct ngx_chain_s {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2224 ngx_buf_t *buf;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2225 ngx_chain_t *next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2226 };
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2227 </programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2228
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2229 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2230 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	2231 chain link.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2232 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2233
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2234 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2235 An example of using buffers and chains:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2236 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2237
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2238
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2239 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2240 ngx_chain_t *
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2241 ngx_get_my_chain(ngx_pool_t *pool)
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 ngx_buf_t *b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2244 ngx_chain_t out, cl, **ll;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2245
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2246 /* first buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2247 cl = ngx_alloc_chain_link(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2248 if (cl == NULL) { /* error */ }
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 b = ngx_calloc_buf(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2251 if (b == NULL) { /* error */ }
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 b->start = (u_char *) "foo";
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2254 b->pos = b->start;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2255 b->end = b->start + 3;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2256 b->last = b->end;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2257 b->memory = 1; /* read-only memory */
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 cl->buf = b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2260 out = cl;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2261 ll = &cl->next;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2262
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2263 /* second buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2264 cl = ngx_alloc_chain_link(pool);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2265 if (cl == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2266
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2267 b = ngx_create_temp_buf(pool, 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2268 if (b == NULL) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2269
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2270 b->last = ngx_cpymem(b->last, "foo", 3);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2271
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2272 cl->buf = b;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2273 cl->next = NULL;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2274 *ll = cl;
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 return out;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2277 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2278 </programlisting>
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 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2281
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 <section name="Networking" id="networking">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2284
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2285
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2286 <!--
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2287 <section name="Network data types" id="network_data_types">
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2290 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	2291 address...
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2292 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2293
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2294 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2295 -->
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2296
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2297 <section name="Connection" id="connection">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2298
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2299 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2300 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	2301 socket descriptor.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2302 It includes the following fields:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2303 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2304
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2305 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2306 <list type="bullet">
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 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2309 <literal>fd</literal> — Socket descriptor
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2310 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2311
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2312 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2313 <literal>data</literal> — Arbitrary connection context.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2314 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	2315 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	2316 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2317
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2318 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2319 <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	2320 the connection.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2321 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2322
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2323 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2324 <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	2325 <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	2326 for the connection.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2327 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2328
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2329 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2330 <literal>pool</literal> — Connection pool.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2331 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2332
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2333 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2334 <literal>log</literal> — Connection log.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2335 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2336
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2337 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2338 <literal>sockaddr</literal>, <literal>socklen</literal>,
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2339 <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	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>local_sockaddr</literal>, <literal>local_socklen</literal> — Local
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2344 socket address in binary form.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2345 Initially, these fields are empty.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2346 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	2347 local socket address.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2348 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2349
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2350 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2351 <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	2352 - 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	2353 the connection.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2354 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2355
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2356 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2357 <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	2358 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2359
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2360 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2361 <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	2362 makes it eligible for reuse.
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
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2365 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2366 <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	2367 and needs to be closed.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2368 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2369
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2370 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2371 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2372
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2373 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2374 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	2375 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	2376 <literal>ngx_ssl_connection_t</literal> structure, keeping all SSL-related data
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2377 for the connection, including <literal>SSL_CTX</literal> and
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2378 <literal>SSL</literal>.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2379 The <literal>recv</literal>, <literal>send</literal>,
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2380 <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	2381 set to SSL-enabled functions as well.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2382 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2383
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2384 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2385 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	2386 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	2387 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	2388 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	2389 To retrieve a connection structure, use the
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2390 <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	2391 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	2392 to be wrapped in a connection structure.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2393 </para>
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 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2396 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	2397 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	2398 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	2399 <literal>ngx_reusable_connection(c, reusable)</literal> function.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2400 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	2401 <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	2402 connection into the <literal>reusable_connections_queue</literal> of the cycle.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2403 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	2404 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	2405 it calls <literal>ngx_drain_connections()</literal> to release a
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2406 specific number of reusable connections.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2407 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	2408 handler is called which is supposed to free the connection by calling
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2409 <literal>ngx_close_connection(c)</literal> and make it available for reuse.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2410 To exit the state when a connection can be reused
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2411 <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	2412 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	2413 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	2414 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2415
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2416 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2417
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2418
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2419 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2420
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2421
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2422 <section name="Events" id="events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2423
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2424
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2425 <section name="Event" id="event">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2426
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2427 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2428 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	2429 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	2430 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2431
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2432 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2433 Fields in <literal>ngx_event_t</literal> include:
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2434 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2435
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2436 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2437 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2438
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2439 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2440 <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	2441 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	2442 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2443
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2444 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2445 <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	2446 happens.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2447 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2448
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2449 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2450 <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	2451 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	2452 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2453
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2454 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2455 <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	2456 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	2457 <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	2458 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2459
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2460 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2461 <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	2462 I/O notification.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2463 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2464
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2465 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2466 <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	2467 limiting.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2468 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2469
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2470 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2471 <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	2472 the timer tree.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2473 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2474
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2475 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2476 <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	2477 not yet expired.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2478 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2479
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2480 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2481 <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	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>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	2486 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2487
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 <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	2490 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	2491 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	2492 <literal>epoll</literal> event or
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2493 <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	2494 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2495
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2496 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2497 <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	2498 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	2499 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2500
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2501 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2502 <literal>cancelable</literal> — Timer event flag, used during graceful shutdown
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2503 of nginx workers, to signal that the event handler needs to be called even
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2504 though the event timeout has not yet expired.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2505 The flag provides a way to finalize certain activities, for example flush log
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2506 files.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2507 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2508
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2509 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2510 <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	2511 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2512
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2513 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2514 <literal>queue</literal> — Queue node for posting the event to a queue.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2515 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2516
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2517 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2518 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2519
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2520 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2521
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2522
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2523 <section name="I/O events" id="i_o_events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2524
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2525 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2526 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	2527 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	2528 <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	2529 socket is ready for reading or writing.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2530 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	2531 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	2532 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	2533 repeated read notification until more data arrives on the socket.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2534 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	2535 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	2536 converts the notifications to Edge-Triggered.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2537 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	2538 on different platforms, the functions
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2539 <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	2540 <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	2541 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	2542 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	2543 event handler.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2544 </para>
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 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2547
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 name="Timer events" id="timer_events">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2552 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	2553 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	2554 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	2555 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	2556 stores all timeouts currently set.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2557 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	2558 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	2559 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	2560 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	2561 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	2562 for I/O events and for expiring timeout events.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2563 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2564
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2565 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2566
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2567
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2568 <section name="Posted events" id="posted_events">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2569
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2570 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2571 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	2572 point later within the current event loop iteration.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2573 Posting events is a good practice for simplifying code and escaping stack
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2574 overflows.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2575 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	2576 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	2577 <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	2578 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	2579 <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	2580 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	2581 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	2582 events are already handled.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2583 The function <literal>ngx_event_process_posted()</literal> is called to process
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2584 an event queue.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2585 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	2586 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	2587 within the current event loop iteration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2588 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2589
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2590 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2591 An example:
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2595 <programlisting>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2596 void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2597 ngx_my_connection_read(ngx_connection_t *c)
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 ngx_event_t *rev;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2600
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2601 rev = c->read;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2602
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2603 ngx_add_timer(rev, 1000);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2604
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2605 rev->handler = ngx_my_read_handler;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2606
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2607 ngx_my_read(rev);
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2608 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2609
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2610
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2611 void
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2612 ngx_my_read_handler(ngx_event_t *rev)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2613 {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2614 ssize_t n;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2615 ngx_connection_t *c;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2616 u_char buf[256];
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2617
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2618 if (rev->timedout) { /* timeout expired */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2619
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2620 c = rev->data;
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2621
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2622 while (rev->ready) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2623 n = c->recv(c, buf, sizeof(buf));
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2624
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2625 if (n == NGX_AGAIN) {
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2626 break;
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2629 if (n == NGX_ERROR) { /* error */ }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2630
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2631 /* process buf */
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2632 }
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2633
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2634 if (ngx_handle_read_event(rev, 0) != NGX_OK) { /* error */ }
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 </programlisting>
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 </section>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2641 <section name="Event loop" id="event_loop">
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 <para>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2644 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	2645 event loop.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2646 (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	2647 <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	2648 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	2649 <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	2650 repeatedly until the process exits.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2651 </para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2652
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2653 <para>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2654 The event loop has the following stages:
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2655
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2656 <list type="bullet">
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 <listitem>
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2659 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	2660 <literal>ngx_event_find_timer()</literal>.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2661 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	2662 number of milliseconds until the node expires.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2663 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2664
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2665 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2666 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	2667 mechanism, chosen by nginx configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2668 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	2669 timeout expires.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2670 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	2671 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	2672 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	2673 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	2674 events.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2675 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2676
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2677 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2678 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	2679 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	2680 unexpired timeout is found.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2681 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	2682 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	2683 </listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2684
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2685 <listitem>
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	2686 Process posted events by calling <literal>ngx_event_process_posted()</literal>.
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2687 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	2688 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	2689 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2690
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2691 </list>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2692 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2693
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2694 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2695 All nginx processes handle signals as well.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2696 Signal handlers only set global variables which are checked after the
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2697 <literal>ngx_process_events_and_timers()</literal> call.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2698 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2699
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2700 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2701
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2702
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2703 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2704
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2705
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2706 <section name="Processes" id="processes">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2707
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2708 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2709 There are several types of processes in nginx.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2710 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	2711 global variable:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2712 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2713
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2714 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2715
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2716 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2717
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2718 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2719 <literal>NGX_PROCESS_MASTER</literal> — the master process runs the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2720 <literal>ngx_master_process_cycle()</literal> function.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2721 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	2722 It reads configuration, creates cycles, starts and controls child processes
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2725
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2726 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2727
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2728 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2729
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2730 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2731 <literal>NGX_PROCESS_WORKER</literal> — the worker process runs the
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2732 <literal>ngx_worker_process_cycle()</literal> function.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2733 Worker processes are started by master and handle client connections.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2734 They also respond to signals and channel commands, sent from master
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2735 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2736
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2737
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2738 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2739
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2740 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2741
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2742 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2743 <literal>NGX_PROCESS_SINGLE</literal> — single process is the only type
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2744 of processes which exist in the <literal>master_process off</literal> mode.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2745 The cycle function for this process is
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2746 <literal>ngx_single_process_cycle()</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2747 This process creates cycles and handles client connections
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2748 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2749
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2750
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2751 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2752
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2753 <listitem>
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 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2756 <literal>NGX_PROCESS_HELPER</literal> — currently, there are two types of
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2757 helper processes: cache manager and cache loader.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2758 Both of them share the same cycle function
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2759 <literal>ngx_cache_manager_process_cycle()</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2760 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2761
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2762
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2763 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2764
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2765 </list>
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 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2768 All nginx processes handle the following signals:
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2769 </para>
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 <list type="bullet">
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2772
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2773 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2774
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2775 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2776 <literal>NGX_SHUTDOWN_SIGNAL</literal> (<literal>SIGQUIT</literal>) — graceful
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2777 shutdown.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2778 Upon receiving this signal master process sends shutdown signal to all child
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2779 processes.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2780 When no child processes are left, master destroys cycle pool and exits.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2781 A worker process which received this signal, closes all listening sockets and
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2782 waits until timeout tree becomes empty, then destroys cycle pool and exits.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2783 A cache manager process exits right after receiving this signal.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2784 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	2785 signal and immediately reset after being processed.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2786 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	2787 is in shutdown state
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2788 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2789
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 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2792
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2793 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2794
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2795 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2796 <literal>NGX_TERMINATE_SIGNAL</literal> (<literal>SIGTERM</literal>) -
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2797 terminate.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2798 Upon receiving this signal master process sends terminate signal to all child
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2799 processes.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2800 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	2801 <literal>SIGKILL</literal> signal.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2802 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	2803 A worker or cache manager process which received this signal destroys cycle
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2804 pool and exits.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2805 The variable <literal>ngx_terminate</literal> is set to one after receiving
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2806 this signal
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2807 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2808
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2809
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2810 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2811
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2812 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2813
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2814 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2815 <literal>NGX_NOACCEPT_SIGNAL</literal> (<literal>SIGWINCH</literal>)
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2816 - gracefully shut down worker processes
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_RECONFIGURE_SIGNAL</literal> (<literal>SIGHUP</literal>) -
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2826 reconfigure.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2827 Upon receiving this signal master process creates a new cycle from
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2828 configuration file.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2829 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	2830 child processes are started.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2831 Meanwhile, the old processes receive the shutdown signal.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2832 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	2833 one until all clients, tied to the old cycle, are gone.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2834 Worker and helper processes ignore this signal
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2835 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2836
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 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2839
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2840 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2841
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2842 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2843 <literal>NGX_REOPEN_SIGNAL</literal> (<literal>SIGUSR1</literal>) — reopen
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2844 files.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2845 Master process passes this signal to workers.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2846 Worker processes reopen all <literal>open_files</literal> from the cycle
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2847 </para>
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
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2850 </listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2851
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2852 <listitem>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2853
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2854 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	2855 <literal>NGX_CHANGEBIN_SIGNAL</literal> (<literal>SIGUSR2</literal>) — change
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2856 nginx binary.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2857 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	2858 sockets.
1936 8f996938fe23 Style: proper quotes usage. Vladimir Homutov <vl@nginx.com> parents: 1935 diff changeset	2859 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	2860 text format, where descriptor numbers separated with semicolons.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2861 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	2862 cycle.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2863 Other 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 </list>
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>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2872 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	2873 signals, master process normally does not pass any signals to workers and
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2874 helpers with the standard <literal>kill()</literal> syscall.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2875 Instead, nginx uses inter-process channels which allow sending messages between
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2876 all nginx processes.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2877 Currently, however, messages are only sent from master to its children.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2878 Those messages carry the same signals.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2879 The channels are socketpairs with their ends in different processes.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2880 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2881
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2882 <para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2883 When running nginx binary, several values can be specified next to
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2884 <literal>-s</literal> parameter.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2885 Those values are <literal>stop</literal>, <literal>quit</literal>,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2886 <literal>reopen</literal>, <literal>reload</literal>.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2887 They are converted to signals <literal>NGX_TERMINATE_SIGNAL</literal>,
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2888 <literal>NGX_SHUTDOWN_SIGNAL</literal>, <literal>NGX_REOPEN_SIGNAL</literal>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2889 and <literal>NGX_RECONFIGURE_SIGNAL</literal> and sent to the nginx master
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2890 process, whose pid is read from nginx pid file.
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2891 </para>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2892
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2893 </section>
b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2894
1983 7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2895 <section name="Threads" id="threads">
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2896
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2897 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2898 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	2899 into a separate thread.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2900 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	2901 <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	2902 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	2903 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	2904 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	2905 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	2906 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2907
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2908 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2909 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	2910 are available:
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2911 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2912 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	2913
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2914 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	2915 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	2916 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	2917 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	2918
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2919 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	2920
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2921 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	2922 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	2923 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	2924 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	2925 ngx_log_t *log);
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2926 </programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2927 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2928
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2929 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2930 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	2931 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	2932 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	2933 (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	2934 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	2935 that process a queue of tasks.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2936 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	2937 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2938
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2939 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2940 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	2941 corresponding definitions:
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2942 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2943 struct ngx_thread_task_s {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2944 ngx_thread_task_t *next;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2945 ngx_uint_t id;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2946 void *ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2947 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	2948 ngx_event_t event;
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
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2951 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	2952
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2953 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	2954 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	2955
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2956 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	2957 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	2958
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2959 </programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2960 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	2961 reference to thread pool by calling
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2962 <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	2963 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	2964 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	2965 </para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2966
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2967 <para>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2968 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	2969 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	2970 <literal>tp</literal>.
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2971
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2972 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	2973 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	2974 handler:
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2975 <programlisting>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2976 typedef struct {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2977 int foo;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2978 } my_thread_ctx_t;
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
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2981 static void
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2982 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	2983 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2984 my_thread_ctx_t *ctx = data;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2985
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2986 /* 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	2987 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2988
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2989
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2990 static void
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2991 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	2992 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2993 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	2994
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2995 /* executed in nginx event loop */
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2996 }
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2997
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2998
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	2999 ngx_int_t
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3000 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	3001 {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3002 my_thread_ctx_t *ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3003 ngx_thread_task_t *task;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3004
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3005 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	3006 if (task == NULL) {
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3007 return NGX_ERROR;
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 ctx = task->ctx;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3011
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3012 ctx->foo = 42;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3013
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3014 task->handler = my_thread_func;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3015 task->event.handler = my_thread_completion;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3016 task->event.data = ctx;
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 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	3019 return NGX_ERROR;
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3020 }
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 return NGX_OK;
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 </programlisting>
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 </para>
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 </section>
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3029
7660d6390a9d Added the "Threads" section into the development guide. Vladimir Homutov <vl@nginx.com> parents: 1982 diff changeset	3030
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3031 <section name="Modules" id="Modules">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3032
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3033 <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	3034 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3035 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	3036 at least two files:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3037 <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	3038 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	3039 the module, for example:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3040 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3041 ngx_module_type=CORE
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3042 ngx_module_name=ngx_foo_module
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3043 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	3044
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3045 . auto/module
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3046
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3047 ngx_addon_name=$ngx_module_name
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3048 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3049 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	3050 following variables:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3051 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3052
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3053 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3054 <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	3055 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	3056 <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	3057 <literal>HTTP_AUX_FILTER</literal>, <literal>MAIL</literal>,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3058 <literal>STREAM</literal>, or <literal>MISC</literal>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3059 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3060
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3061 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3062 <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	3063 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	3064 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	3065 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	3066 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	3067 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3068
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3069 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3070 <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	3071 console output text of the configure script.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3072 </listitem>
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 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3075 <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	3076 files used to compile the module.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3077 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	3078 module source.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3079 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3080
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3081 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3082 <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	3083 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3084
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3085 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3086 <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	3087 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3088
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3089 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3090 <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	3091 module.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3092 For example, libpthread would be linked using
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3093 <literal>ngx_module_libs=-lpthread</literal>.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3094 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	3095 nginx:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3096 <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	3097 <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	3098 <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	3099 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3100
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3101 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3102 <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	3103 <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	3104 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	3105 linking type.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3106 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3107
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3108 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3109 <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	3110 is useful for <literal>HTTP_FILTER</literal> and
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3111 <literal>HTTP_AUX_FILTER</literal> module types.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3112 The order is stored in a reverse list.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3113
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3114 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3115 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	3116 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	3117 This reads the data for other filters.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3118 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	3119 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	3120 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3121
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3122 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3123 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	3124 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	3125 after.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3126 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	3127 to be currently loaded.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3128 </para>
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 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3131 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	3132 “<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	3133 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	3134 For other module types the default is empty.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3135 </para>
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>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3138
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3139 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3140
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3141 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	3142 <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	3143 <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	3144 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3145
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3146 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3147
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3148
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3149 <section name="Core modules" id="core_modules">
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 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	3153 implemented as modules.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3154 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	3155 <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	3156 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3157 struct ngx_module_s {
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 /* private part is omitted */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3160
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3161 void *ctx;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3162 ngx_command_t *commands;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3163 ngx_uint_t type;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3164
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3165 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	3166
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3167 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	3168
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3169 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	3170 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	3171 void (exit_thread)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3172 void (exit_process)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3173
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3174 void (exit_master)(ngx_cycle_t cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3175
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3176 /* stubs for future extensions are omitted */
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 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3179 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	3180 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	3181 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3182
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3183 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3184 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	3185 recognizes specific configuration directives, specified in the
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3186 <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	3187 nginx lifecycle.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3188 The module lifecycle consists of the following events:
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 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3191
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3192 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3193 Configuration directive handlers are called as they appear
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3194 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	3195 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3196
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3197 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3198 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	3199 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	3200 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3201
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3202 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3203 The master process creates worker process(es) and
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3204 <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	3205 </listitem>
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 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3208 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	3209 the <literal>exit_process</literal> handler
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3210 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3211
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3212 <listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3213 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	3214 exiting.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3215 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3216
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3217 </list>
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 <note>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3220 <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	3221 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	3222 </note>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3223
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3224 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	3225 <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	3226 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	3227 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	3228 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3229
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3230 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3231 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	3232 <literal>ctx</literal> field.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3233 There are several types of modules:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3234 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3235 <listitem><literal>NGX_CORE_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3236 <listitem><literal>NGX_EVENT_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3237 <listitem><literal>NGX_HTTP_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3238 <listitem><literal>NGX_MAIL_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3239 <listitem><literal>NGX_STREAM_MODULE</literal></listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3240 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3241 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	3242 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	3243 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	3244 problem domains, like handling events or http requests.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3245 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3246
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3247 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3248 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	3249 <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	3250 <literal>ngx_thread_pool_module</literal>,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3251 <literal>ngx_openssl_module</literal>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3252 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	3253 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	3254 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3255 typedef struct {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3256 ngx_str_t name;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3257 void (create_conf)(ngx_cycle_t *cycle);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3258 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	3259 } ngx_core_module_t;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3260 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3261 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	3262 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	3263 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	3264 correspondingly.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3265 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	3266 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	3267 was parsed successfully.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3268 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	3269 configuration and sets default values.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3270 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	3271 perform sanity checks and complete initialization.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3272 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3273
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 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	3276 this:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3277 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3278 /*
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3279 * Copyright (C) Author.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3280 */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3281
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3282
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3283 #include <ngx_config.h>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3284 #include <ngx_core.h>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3285
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3286
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3287 typedef struct {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3288 ngx_flag_t enable;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3289 } ngx_foo_conf_t;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3290
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3291
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3292 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	3293 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	3294
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3295 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	3296 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	3297
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3298
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3299 static ngx_command_t ngx_foo_commands[] = {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3300
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3301 { ngx_string("foo_enabled"),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3302 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	3303 ngx_conf_set_flag_slot,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3304 0,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3305 offsetof(ngx_foo_conf_t, enable),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3306 &ngx_foo_enable_post },
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 ngx_null_command
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 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	3313 ngx_string("foo"),
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3314 ngx_foo_create_conf,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3315 ngx_foo_init_conf
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3316 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3317
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3318
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3319 ngx_module_t ngx_foo_module = {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3320 NGX_MODULE_V1,
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3321 &ngx_foo_module_ctx, /* module context */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3322 ngx_foo_commands, /* module directives */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3323 NGX_CORE_MODULE, /* module type */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3324 NULL, /* init master */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3325 NULL, /* init module */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3326 NULL, /* init process */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3327 NULL, /* init thread */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3328 NULL, /* exit thread */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3329 NULL, /* exit process */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3330 NULL, /* exit master */
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3331 NGX_MODULE_V1_PADDING
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3332 };
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3333
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3334
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3335 static void *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3336 ngx_foo_create_conf(ngx_cycle_t *cycle)
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3337 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3338 ngx_foo_conf_t *fcf;
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 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	3341 if (fcf == NULL) {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3342 return NULL;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3343 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3344
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3345 fcf->enable = NGX_CONF_UNSET;
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 return fcf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3348 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3349
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3350
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3351 static char *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3352 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	3353 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3354 ngx_foo_conf_t *fcf = conf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3355
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3356 ngx_conf_init_value(fcf->enable, 0);
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3357
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3358 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3359 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3360
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3361
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3362 static char *
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3363 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	3364 {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3365 ngx_flag_t *fp = data;
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 if (*fp == 0) {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3368 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3369 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3370
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3371 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	3372
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3373 return NGX_CONF_OK;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3374 }
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3375 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3376 </para>
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 </section>
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
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3381 <section name="Configuration directives" id="config_directives">
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 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3384 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	3385 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	3386 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	3387 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3388 struct ngx_command_s {
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3389 ngx_str_t name;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3390 ngx_uint_t type;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3391 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	3392 ngx_uint_t conf;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3393 ngx_uint_t offset;
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3394 void *post;
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 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3397 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	3398 “<literal>ngx_null_command</literal>”.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3399 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	3400 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	3401 “<literal>listen</literal>”.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3402 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	3403 command type and other properties using corresponding flags.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3404 Arguments flags:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3405
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3406 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3407
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3408 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3409 <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	3410 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3411
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3412 <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	3413
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3414 <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	3415
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3416 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3417 <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	3418 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3419
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3420 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3421 <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	3422 or other combinations
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3423 </listitem>
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 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3426
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3427 Directive types:
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3428
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3429 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3430
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3431 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3432 <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	3433 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	3434 to handle contents inside.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3435 </listitem>
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_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	3439 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	3440 strings.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3441 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3442 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3443
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3444 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	3445 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	3446 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3447
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3448 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3449 <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	3450 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3451
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3452 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3453 <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	3454 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3455
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3456 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3457 <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	3458 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3459
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3460 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3461 <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	3462 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3463
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3464 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3465 <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	3466 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3467
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3468 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3469 <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	3470 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3471
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3472 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3473 <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	3474 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3475
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3476 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3477 <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	3478 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3479
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3480 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3481 <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	3482 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3483
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3484 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3485 <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	3486 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3487
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3488 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3489 <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	3490 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3491
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3492 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3493 <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	3494 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3495
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3496 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3497 <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	3498 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3499
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3500 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3501 <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	3502 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3503
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3504 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3505 <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	3506 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	3507 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3508 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3509 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	3510 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	3511 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	3512 store their values in distinct places.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3513 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3514
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3515 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3516 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	3517 and stores parsed values into corresponding configuration.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3518 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	3519
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3520 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3521
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3522 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3523 <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	3524 “<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	3525 <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	3526 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3527
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3528 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3529 <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	3530 <literal>ngx_str_t</literal> type
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3531 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3532
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3533 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3534 <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	3535 <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	3536 The array is created if not yet exists
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3537 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3538
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3539 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3540 <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	3541 <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	3542 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	3543 The array is created if not yet exists
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3544 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3545
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3546 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3547 <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	3548 to a <literal>ngx_int_t</literal> value
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3549 </listitem>
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_size_slot</literal> — converts
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3553 <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	3554 in bytes
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_off_slot</literal> — converts
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3559 <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	3560 in bytes
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3561 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3562
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3563 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3564 <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	3565 <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	3566 in milliseconds
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3567 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3568
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3569 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3570 <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	3571 <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	3572 in seconds
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_bufs_slot</literal> — converts two arguments
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3577 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	3578 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	3579 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3580
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3581 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3582 <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	3583 into <literal>ngx_uint_t</literal> value.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3584 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	3585 <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	3586 integer values
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3587 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3588
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3589 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3590 <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	3591 <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	3592 forming a bitmask.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3593 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	3594 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	3595 mask values
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>set_path_slot</literal> — converts arguments to
1928 2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3600 <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	3601 See the
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3602 <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	3603 directive description for details
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3604 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3605
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3606 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3607 <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	3608 mask.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3609 See the
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3610 <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	3611 directive description for details
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3612 </listitem>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3613
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3614 </list>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3615
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3616 </para>
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 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3619 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	3620 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	3621 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	3622 <literal>NGX_DIRECT_CONF</literal> flag.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3623 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	3624 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	3625 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	3626 some limit.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3627 In this modules, configuration structure is more complex.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3628 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	3629 they manage their configuration.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3630
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3631 <list type="bullet">
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3632 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3633 <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	3634 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3635
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3636 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3637 <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	3638 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3639
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3640 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3641 <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	3642 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3643
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3644 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3645 <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	3646 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3647
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3648 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3649 <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	3650 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3651
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3652 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3653 <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	3654 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3655
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3656 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3657 <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	3658 </listitem>
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>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3661
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3662 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3663
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3664 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3665 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	3666 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	3667 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	3668 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3669
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3670 <para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3671 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	3672 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	3673 data to the main handler.
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3674 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	3675 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	3676 <programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3677 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	3678 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	3679 </programlisting>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3680 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	3681 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	3682 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	3683 </para>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3684
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3685 </section>
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3686
2c14a16c61eb Added modules section to development guide. Vladimir Homutov <vl@nginx.com> parents: 1920 diff changeset	3687 </section>
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
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3690 <section name="HTTP" id="http">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3691
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3692
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3693 <section name="Connection" id="http_connection">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3694
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3695 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3696 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	3697 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3698
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3699 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3700
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3701 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3702 <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	3703 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	3704 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	3705 The object wraps the newly accepted client socket.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3706 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	3707 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	3708 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3709
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3710 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3711 <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	3712 an HTTP connection.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3713 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	3714 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	3715 <literal>data</literal> field.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3716 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	3717 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	3718 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3719
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3720 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3721 <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	3722 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	3723 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	3724 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	3725 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3726
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3727 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3728 <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	3729 which reads client request line.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3730 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	3731 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	3732 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	3733 <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	3734 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	3735 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	3736 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	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_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	3741 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	3742 client request header
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3743 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3744
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3745 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3746 <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	3747 is completely read and parsed.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3748 This function runs request phases from
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3749 <literal>NGX_HTTP_POST_READ_PHASE</literal> to
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3750 <literal>NGX_HTTP_CONTENT_PHASE</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3751 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	3752 chain.
1979 ff28ca78bef3 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 1976 diff changeset	3753 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	3754 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	3755 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3756
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3757 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3758 <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	3759 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	3760 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	3761 response.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3762 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	3763 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	3764 sending outstanding data
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3765 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3766
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3767 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3768 <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	3769 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	3770 If client connection keepalive feature is enabled,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3771 <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	3772 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	3773 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	3774 request and the connection
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3775 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3776
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3777 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3778
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3779 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3780
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3781
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3782 <section name="Request" id="http_request">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3783
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3784 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3785 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	3786 created. Some of the fields of this object:
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3787 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3788
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3789 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3790
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3791 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3792
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3793 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3794 <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	3795 client connection object.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3796 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	3797 one main request and its subrequests.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3798 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	3799 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3800
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3801 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3802 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	3803 <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	3804 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	3805 connection.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3806 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	3807 output its response to the client.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3808 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	3809 output
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3810 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3811
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3812 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3813
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3814 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3815
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3816 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3817 <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	3818 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	3819 (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	3820 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	3821 <literal>ctx_index</literal> position.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3822 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	3823 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3824
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3825 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3826
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3827 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3828 <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	3829 <literal>module</literal>'s context
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3830 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3831
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3832 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3833 <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	3834 as <literal>module</literal>'s context
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3835 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3836
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3837 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3838
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3839 </listitem>
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>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3842 <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	3843 configurations.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3844 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	3845 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3846
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3847 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3848 <literal>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	3849 read and write event handlers for the request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3850 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	3851 set as both read and write event handlers.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3852 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	3853 <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	3854 </listitem>
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>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	3858 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3859
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3860 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3861 <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	3862 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3863
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3864 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3865 <literal>pool</literal> — request pool.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3866 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	3867 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	3868 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	3869 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	3870 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3871
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3872 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3873 <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	3874 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3875
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3876 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3877 <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	3878 objects.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3879 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	3880 <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	3881 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	3882 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	3883 <literal>status</literal> etc
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3884 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3885
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3886 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3887 <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	3888 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3889
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3890 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3891 <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	3892 created.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3893 Used for tracking request duration
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3894 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3895
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3896 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3897 <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	3898 client HTTP request method.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3899 Numeric values for methods are defined in
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3900 <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	3901 <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	3902 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3903
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3904 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3905 <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	3906 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	3907 “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	3908 <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	3909 versions
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3910 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3911
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3912 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3913 <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	3914 and URI
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3915 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3916
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3917 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3918 <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	3919 extention.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3920 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	3921 normalization.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3922 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	3923 redirects
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3924 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3925
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3926 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3927 <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	3928 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	3929 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	3930 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3931
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3932 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3933 <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	3934 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3935
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3936 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3937 <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	3938 order they are sent and created.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3939 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	3940 when parts of it are created by subrequests
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3941 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3942
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3943 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3944 <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	3945 called when a subrequest gets finalized.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3946 Unused for main requests
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3947 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3948
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3949 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3950
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3951 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3952 <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	3953 resumed.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3954 Starting or resuming is done by calling the request's
1932 937e03180281 Fixed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1929 diff changeset	3955 <literal>write_event_handler</literal>.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3956 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	3957 request phases and then produces the output.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3958 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3959
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3960 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3961 A request is usually posted by the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3962 <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	3963 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	3964 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	3965 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	3966 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	3967 posted requests.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3968 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	3969 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3970
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3971 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3972
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3973 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3974 <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	3975 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3976
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3977 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3978 <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	3979 by the last regex match of the request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3980 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	3981 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	3982 etc.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3983 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	3984 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	3985 <literal>captures</literal> holds captures boundaries,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3986 <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	3987 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	3988 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	3989 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3990
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3991 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	3992 <literal>count</literal> — request reference counter.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3993 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	3994 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	3995 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	3996 should be called.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3997 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	3998 counter
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	3999 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4000
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4001 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4002 <literal>subrequests</literal> — current subrequest nesting level.
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4003 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	4004 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	4005 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	4006 <literal>NGX_HTTP_MAX_SUBREQUESTS</literal> constant
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4007 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4008
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4009 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4010 <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	4011 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	4012 <literal>NGX_HTTP_MAX_URI_CHANGES</literal> constant.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4013 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	4014 In the latter case an error is generated.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4015 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	4016 normal or named locations
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4017 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4018
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4019 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4020 <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	4021 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	4022 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	4023 thread operations) and active cache lock
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4024 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4025
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4026 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4027 <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	4028 output produced by the request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4029 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	4030 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	4031 of free output_buffers etc.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4032 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	4033 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4034
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4035 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4036 <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	4037 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	4038 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4039
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4040 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4041 <para>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4042 <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	4043 supported.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4044 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	4045 value
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4046 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4047 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4048
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4049 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4050 <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	4051 been sent by the request
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4052 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4053
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4054 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4055 <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	4056 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	4057 redirect or be a subrequest.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4058 Internal requests are allowed to enter internal locations
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4059 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4060
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4061 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4062 <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	4063 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	4064 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4065
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4066 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4067 <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	4068 allowed to be sent while processing a subrequest
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4071 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4072 <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	4073 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	4074 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	4075 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	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>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	4080 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	4081 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	4082 sendfile is enabled.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4083 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	4084 set them.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4085 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	4086 <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	4087 request output should come in memory buffers.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4088 Filters called later in filter chain set
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4089 <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	4090 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	4091 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4092
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4093 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4094 <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	4095 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	4096 file buffers.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4097 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	4098 it's sent </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 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4101
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4102 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4103
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4104
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4105 <section name="Configuration" id="http_conf">
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 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4108 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	4109 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4110
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4111 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4112
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4113 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4114 Main configuration.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4115 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	4116 configuration.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4117 It stores global settings for a module
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4118 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4119
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 Server configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	4122 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	4123 It stores server-specific settings for a module
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4124 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4125
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4126 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4127 Location configuration.
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	4128 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	4129 This configuration stores settings specific to a location
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4130 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4131
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4132 </list>
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 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4135 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	4136 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	4137 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	4138 configuration.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4139 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	4140 type.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4141 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4142
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4143 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4144 typedef struct {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4145 ngx_uint_t foo;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4146 } ngx_http_foo_loc_conf_t;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4147
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 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	4150 NULL, /* preconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4151 NULL, /* postconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4152
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4153 NULL, /* create main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4154 NULL, /* init main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4155
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4156 NULL, /* create server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4157 NULL, /* merge server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4158
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4159 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	4160 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	4161 };
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4164 static void *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4165 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	4166 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4167 ngx_http_foo_loc_conf_t *conf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4168
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4169 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	4170 if (conf == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4171 return NULL;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4172 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4173
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4174 conf->foo = NGX_CONF_UNSET_UINT;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4175
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4176 return conf;
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4179
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4180 static char *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4181 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	4182 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4183 ngx_http_foo_loc_conf_t *prev = parent;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4184 ngx_http_foo_loc_conf_t *conf = child;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4185
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4186 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	4187 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4188 </programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4189
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4190 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4191 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	4192 function creates a new configuration structure and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4193 <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	4194 another configuration from a higher level.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4195 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	4196 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	4197 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	4198 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	4199 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	4200 settings at any level of nginx configuration file.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4201 Eventually configurations are merged down.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4202 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	4203 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	4204 <literal>NGX_CONF_UNSET_UINT</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4205 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	4206 <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	4207 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	4208 explicit value.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4209 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	4210 <literal>src/core/ngx_conf_file.h</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4211 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4212
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4213 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4214 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	4215 macros are available.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4216 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	4217 </para>
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 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4220
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4221 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4222 <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	4223 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4224
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4225 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4226 <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	4227 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4228
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4229 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4230 <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	4231 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4232
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4233 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4234
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4235 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4236 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	4237 standard nginx core module
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4238 <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	4239 and changes
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4240 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	4241 structure.
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4244 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4245 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	4246
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 static ngx_command_t ngx_http_foo_commands[] = {
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 { ngx_string("foo"),
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4251 NGX_HTTP_LOC_CONF\|NGX_CONF_NOARGS,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4252 ngx_http_foo,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4253 0,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4254 0,
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4255 NULL },
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4256
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4257 ngx_null_command
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4258 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4259
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4260
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4261 static char *
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4262 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	4263 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4264 ngx_http_core_loc_conf_t *clcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4265
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4266 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	4267 clcf->handler = ngx_http_bar_handler;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4268
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4269 return NGX_CONF_OK;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4270 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4271 </programlisting>
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 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4274 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	4275 modules.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4276 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4277
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4278 <list type="bullet">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4279
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4280 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4281 <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	4282 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4283
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4284 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4285 <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	4286 </listitem>
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 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4289 <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	4290 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4291
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4292 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4293
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4294 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4295 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	4296 <literal>ngx_http_request_t</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4297 Main configuration of a request never changes.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4298 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	4299 server for a request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4300 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	4301 rewrite or internal redirect.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4302 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	4303 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4304
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4305 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4306 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4307 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	4308 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4309 ngx_http_foo_loc_conf_t *flcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4310
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4311 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	4312
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4313 ...
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4314 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4315 </programlisting>
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 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4318
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4319
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4320 <section name="Phases" id="http_phases">
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4321
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4322 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4323 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	4324 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	4325 Most phases allow installing handlers.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4326 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	4327 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	4328 at a specific request processing stage.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4329 Following is the list of nginx HTTP phases.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4330 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4331
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4332 <list type="bullet">
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 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4335 <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	4336 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	4337 installs its handler at this phase.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4338 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	4339 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4340
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4341 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4342 <literal>NGX_HTTP_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	4343 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	4344 The
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4345 <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	4346 installs its handler at this phase
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4347 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4348
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4349 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4350 <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	4351 location based on request URI.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4352 This phase does not allow installing any handlers.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4353 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	4354 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	4355 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	4356 location configuration.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4357 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	4358 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4359
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4360 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4361 <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	4362 <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	4363 chosen at the previous phase
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4364 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4365
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4366 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4367 <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	4368 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	4369 The redirect is done by going back to
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4370 <literal>NGX_HTTP_FIND_CONFIG_PHASE</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4371 No handlers are allowed at this phase
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4372 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4373
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4374 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4375 <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	4376 types of handlers, not associated with access check.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4377 Standard nginx modules
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4378 <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	4379 </link> and
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4380 <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	4381 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	4382 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4383
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4384 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4385 <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	4386 for the request.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4387 Standard nginx modules such as
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4388 <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	4389 <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	4390 </link> register their handlers at this phase.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4391 If configured so by the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4392 <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	4393 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	4394 processing
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4395 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4396
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4397 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4398 <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	4399 <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	4400 case.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4401 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	4402 request is finalized.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4403 No handlers are supported at this phase
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4404 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4405
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4406 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4407 <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	4408 <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	4409 No handlers are allowed at this phase
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4410 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4411
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4412 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4413 <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	4414 is supposed to be generated.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4415 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	4416 example
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4417 <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	4418 <literal>ngx_http_static_module</literal>.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4419 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	4420 the output.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4421 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	4422 If the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4423 <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	4424 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	4425 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	4426 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4427
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4428 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4429 <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	4430 Currently, only the
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4431 <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	4432 registers its handler
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4433 at this stage for access logging.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4434 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	4435 before freeing the request
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4436 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4437
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4438 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4439
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4440 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4441 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	4442 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4443
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4444 <programlisting>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4445 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	4446 NULL, /* preconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4447 ngx_http_foo_init, /* postconfiguration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4448
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4449 NULL, /* create main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4450 NULL, /* init main configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4451
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4452 NULL, /* create server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4453 NULL, /* merge server configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4454
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4455 NULL, /* create location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4456 NULL /* merge location configuration */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4457 };
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4458
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4459
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4460 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4461 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	4462 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4463 ngx_str_t *ua;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4464
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4465 ua = r->headers_in->user_agent;
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 if (ua == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4468 return NGX_DECLINED;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4469 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4470
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4471 /* reject requests with "User-Agent: foo" */
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4472 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	4473 return NGX_HTTP_FORBIDDEN;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4474 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4475
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4476 return NGX_DECLINED;
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4479
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4480 static ngx_int_t
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4481 ngx_http_foo_init(ngx_conf_t *cf)
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4482 {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4483 ngx_http_handler_pt *h;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4484 ngx_http_core_main_conf_t *cmcf;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4485
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4486 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	4487
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4488 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	4489 if (h == NULL) {
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4490 return NGX_ERROR;
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
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4493 *h = ngx_http_foo_handler;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4494
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4495 return NGX_OK;
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4496 }
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4497 </programlisting>
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 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4500 Phase handlers are expected to return specific codes:
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4501 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4502
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4503 <list type="bullet">
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 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4506 <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	4507 </listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4508
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4509 <listitem>
be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4510 <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	4511 phase.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4512 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	4513 </listitem>
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 <listitem>
1935 be7490a66d1b Style: use long dash with non-breaking space where appropriate. Vladimir Homutov <vl@nginx.com> parents: 1932 diff changeset	4516 <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	4517 future event.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4518 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	4519 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	4520 <literal>ngx_http_core_run_phases()</literal>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4521 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4522
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4523 <listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4524 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	4525 finalization code, in particular, HTTP response code.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4526 The request is finalized with the code provided
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4527 </listitem>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4528
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4529 </list>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4530
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4531 <para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4532 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	4533 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	4534 is considered a finalization code.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4535 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	4536 finalization code.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4537 At access phase, in
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4538 <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	4539 mode, returning a code other
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4540 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	4541 a denial.
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4542 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	4543 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	4544 </para>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4545
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4546 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	4547
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	4548
1959 d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4549 <section name="Variables" id="http_variables">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4550
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4551 <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	4552
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4553 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4554 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	4555 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	4556 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	4557 to configuration.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4558 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	4559 <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	4560 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4561 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	4562 ngx_int_t index;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4563
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4564 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	4565 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4566 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	4567 <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	4568 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	4569 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	4570 future use.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4571 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4572
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4573 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4574 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	4575 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	4576 All functions that evaluate variables return
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4577 <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	4578 the variable value:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4579 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4580 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	4581
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4582 typedef struct {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4583 unsigned len:28;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4584
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4585 unsigned valid:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4586 unsigned no_cacheable:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4587 unsigned not_found:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4588 unsigned escape:1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4589
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4590 u_char *data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4591 } ngx_variable_value_t;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4592 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4593 where:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4594 <list type="bullet">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4595
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4596 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4597 <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	4598 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4599
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4600 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4601 <literal>data</literal> — value itself
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4602 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4603
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4604 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4605 <literal>valid</literal> — value is valid
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4606 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4607
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4608 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4609 <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	4610 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	4611 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	4612 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	4613 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4614
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4615 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4616 <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	4617 </listitem>
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 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4620 <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	4621 values that require escaping on output
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4622 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4623
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4624 </list>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4625 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4626
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4627 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4628 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	4629 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	4630 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	4631 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	4632 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	4633 identifying it.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4634 Example of typical usage:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4635 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4636 ngx_http_variable_value_t *v;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4637
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4638 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	4639
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4640 if (v == NULL \|\| v->not_found) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4641 /* 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	4642 return NGX_ERROR;
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
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4645 /* some meaningful value is found */
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4646 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4647 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	4648 <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	4649 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	4650 non-cacheable variables.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4651 </para>
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 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4654 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	4655 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	4656 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	4657 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	4658 used in such cases.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4659 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	4660 <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	4661 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4662
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4663 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4664
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4665
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4666 <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	4667
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4668 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4669 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	4670 is used.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4671 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	4672 flags that control its behaviour:
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 <list type="bullet">
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	4675 <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	4676 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	4677 no conflict will happen.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4678 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	4679 <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	4680 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4681
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	4682 <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	4683 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	4684 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4685
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	4686 <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	4687 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	4688 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	4689 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	4690 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4691
1993 98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	4692 <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	4693 variable is a prefix.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4694 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	4695 variable.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4696 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	4697 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	4698 of specific argument.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4699 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4700
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4701 </list>
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 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	4704 <literal>ngx_http_variable_t</literal>:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4705 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4706 struct ngx_http_variable_s {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4707 ngx_str_t name;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4708 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	4709 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	4710 uintptr_t data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4711 ngx_uint_t flags;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4712 ngx_uint_t index;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4713 };
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4714 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4715
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4716 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	4717 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	4718 <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	4719 <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	4720 the variable.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4721 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4722
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4723 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4724 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	4725 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	4726 into configuration:
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4727 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4728 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	4729
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4730 { 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	4731
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4732 { 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	4733 };
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4734
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4735 static ngx_int_t
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4736 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	4737 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4738 ngx_http_variable_t var, v;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4739
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4740 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	4741 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	4742 if (var == NULL) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4743 return NGX_ERROR;
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
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4746 var->get_handler = v->get_handler;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4747 var->data = v->data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4748 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4749
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4750 return NGX_OK;
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 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4753 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	4754 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	4755 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	4756 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4757
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4758 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4759 The <literal>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	4760 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	4761 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4762 static ngx_int_t
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4763 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	4764 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	4765 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4766 u_char *p;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4767
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4768 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	4769 if (p == NULL) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4770 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4771 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4772
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4773 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	4774 v->valid = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4775 v->no_cacheable = 0;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4776 v->not_found = 0;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4777 v->data = p;
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 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	4783 (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	4784 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	4785 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	4786 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4787
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4788 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4789 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	4790 referred by the variable.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4791 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	4792 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	4793 <programlisting>
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 { 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	4796 ngx_http_variable_request_get_size,
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4797 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	4798 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	4799 ...
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4800
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4801 static void
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4802 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	4803 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	4804 {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4805 ssize_t s, *sp;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4806 ngx_str_t val;
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 val.len = v->len;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4809 val.data = v->data;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4810
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4811 s = ngx_parse_size(&val);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4812
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4813 if (s == NGX_ERROR) {
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4814 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	4815 "invalid size \"%V\"", &val);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4816 return;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4817 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4818
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4819 sp = (ssize_t ) ((char ) r + data);
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4820
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4821 *sp = s;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4822
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4823 return;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4824 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4825 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4826
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4827 </para>
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 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4830
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4831 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4832
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 <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	4835
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4836 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4837 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	4838 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	4839 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4840
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4841 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4842 The complex value description in
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4843 <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	4844 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	4845 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	4846
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4847 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4848 ngx_str_t *value;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4849 ngx_http_complex_value_t cv;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4850 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	4851
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4852 value = cf->args->elts; /* directive arguments */
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 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	4855
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4856 ccv.cf = cf;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4857 ccv.value = &value[1];
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4858 ccv.complex_value = &cv;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4859 ccv.zero = 1;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4860 ccv.conf_prefix = 1;
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 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	4863 return NGX_CONF_ERROR;
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 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4866
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4867 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	4868 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	4869
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4870 <list type="bullet">
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4871
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4872 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4873 <literal>cf</literal> — configuration pointer
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4874 </listitem>
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 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4877 <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	4878 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4879
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4880 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4881 <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	4882 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4883
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4884 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4885 <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	4886 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4887
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4888 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4889 <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	4890 (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	4891 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4892
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4893 <listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4894 <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	4895 (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	4896 </listitem>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4897
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4898 </list>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4899 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	4900 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	4901 dealing with filenames.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4902 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4903
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4904 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4905 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	4906 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	4907 in the expression.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4908 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	4909 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	4910 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	4911 </para>
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 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4914 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	4915 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	4916 declaration.
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4917 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4918
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4919 <para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4920 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	4921 <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	4922 <programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4923 ngx_str_t res;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4924
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4925 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	4926 return NGX_ERROR;
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4927 }
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4928 </programlisting>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4929 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	4930 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	4931 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	4932 </para>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4933
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4934 </section>
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4935
d0aebb2337ec Added the "Variables" section to the development guide. Vladimir Homutov <vl@nginx.com> parents: 1958 diff changeset	4936
1967 ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4937 <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	4938
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4939 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4940 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	4941 <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	4942 structure.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4943 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	4944 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	4945 <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	4946 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	4947 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	4948 request.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4949 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	4950 <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	4951 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	4952 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	4953 <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	4954 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	4955 configured for the server.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4956 The
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4957 <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	4958 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	4959 <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	4960 <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	4961 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	4962 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	4963 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4964
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4965 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4966 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	4967 calling one of the functions
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4968 <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	4969 <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	4970 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4971
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4972 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4973 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	4974 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	4975 <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	4976 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	4977 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	4978 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	4979 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4980
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4981 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4982 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	4983 arguments.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4984 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4985
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4986 <programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4987 ngx_int_t
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4988 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	4989 {
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4990 ngx_str_t uri, args;
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4991
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4992 ngx_str_set(&uri, "/foo");
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4993 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	4994
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4995 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	4996 }
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4997 </programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	4998
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 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	5001 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	5002 argument.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5003 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	5004 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	5005 <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	5006 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5007
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 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	5010 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5011
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5012 <programlisting>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5013 ngx_int_t
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5014 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	5015 {
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5016 ngx_str_t name;
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5017
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5018 ngx_str_set(&name, "foo");
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5019
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5020 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	5021 }
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5022 </programlisting>
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 <para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5025 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	5026 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	5027 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	5028 by nginx modules.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5029 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	5030 location configuration.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5031 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	5032 erased by both redirect functions.
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5033 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5034
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 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	5037 <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	5038 locations.
98b713b0a9fa Language and style fixes in development guide. Roman Arutyunyan <arut@nginx.com> parents: 1983 diff changeset	5039 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	5040 </para>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5041
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5042 </section>
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5043
ef27e3ef0c46 The HTTP request redirection section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1960 diff changeset	5044
1968 69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5045 <section name="Subrequests" id="http_subrequests">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5046
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5047 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5048 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	5049 possibly mixed with other data.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5050 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	5051 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	5052 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	5053 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	5054 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	5055 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	5056 requests.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5057 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5058
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5059 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5060 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	5061 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	5062 based on its own URI.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5063 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5064
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5065 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5066 Subrequest output header is always ignored.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5067 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	5068 <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	5069 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	5070 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5071
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5072 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5073 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	5074 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	5075 <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	5076 connection object.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5077 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	5078 its buffers to the client.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5079 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	5080 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	5081 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	5082 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	5083 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5084
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5085 <list type="bullet">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5086
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5087 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5088 Initially, the main request is active
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5089 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5090
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5091 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5092 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	5093 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5094
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5095 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5096 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	5097 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	5098 sent
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5099 </listitem>
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 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5102 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	5103 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5104
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5105 </list>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5106
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5107 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5108 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	5109 <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	5110 <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	5111 <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	5112 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	5113 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	5114 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	5115 <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	5116 The following flags are available:
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5117 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5118
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5119 <list type="bullet">
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5120
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5121 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5122 <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	5123 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	5124 This only works for proxying subrequests.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5125 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	5126 <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	5127 <literal>ngx_buf_t</literal>
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 <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	5132 <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	5133 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	5134 </listitem>
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 <listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5137 <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	5138 clone of its parent.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5139 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	5140 parent request
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5141 </listitem>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5142
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5143 </list>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5144
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5145 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5146 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	5147 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5148
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5149 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5150 ngx_int_t rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5151 ngx_str_t uri;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5152 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5153
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5154 ...
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5155
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5156 ngx_str_set(&uri, "/foo");
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5157
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5158 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	5159 if (rc == NGX_ERROR) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5160 /* error */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5161 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5162 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5163
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5164 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5165 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	5166 subrequest.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5167 </para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5168
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5169 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5170 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5171 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	5172 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5173 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5174 ngx_http_post_subrequest_t *ps;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5175
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5176 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	5177 if (ps == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5178 return NGX_ERROR;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5179 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5180
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5181 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	5182 ps->data = "foo";
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 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	5185 NGX_HTTP_SUBREQUEST_CLONE);
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
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5188
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5189 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5190 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	5191 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5192 char msg = (char ) data;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5193
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5194 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	5195 "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	5196
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5197 return rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5198 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5199 </programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5200
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5201 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5202 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	5203 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	5204 output.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5205 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	5206 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	5207 buffers passed later.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5208 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	5209 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	5210 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	5211 </para>
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 <programlisting>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5214 ngx_int_t
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5215 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	5216 {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5217 ngx_int_t rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5218 ngx_buf_t *b;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5219 ngx_uint_t last;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5220 ngx_chain_t *cl, out;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5221 ngx_http_request_t *sr;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5222 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	5223
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5224 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	5225 if (ctx == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5226 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	5227 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5228
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5229 last = 0;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5230
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5231 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	5232 if (cl->buf->last_buf) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5233 cl->buf->last_buf = 0;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5234 cl->buf->last_in_chain = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5235 cl->buf->sync = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5236 last = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5237 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5238 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5239
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5240 /* Output explicit output buffers */
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 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	5243
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5244 if (rc == NGX_ERROR \|\| !last) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5245 return rc;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5246 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5247
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5248 /*
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5249 * 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	5250 * 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	5251 * 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	5252 */
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5253
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5254 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	5255 return NGX_ERROR;
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 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	5259
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5260
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5261 /* 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	5262
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5263 b = ngx_calloc_buf(r->pool);
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5264 if (b == NULL) {
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5265 return NGX_ERROR;
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 b->last_buf = 1;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5269
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5270 out.buf = b;
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5271 out.next = NULL;
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 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	5274 }
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5275 </programlisting>
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 <para>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5278 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	5279 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	5280 ngx_http_auth_request_module</link>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5281 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	5282 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	5283 <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	5284 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	5285 Its header is ignored anyway.
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5286 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	5287 </para>
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 </section>
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5290
69908bd68481 The HTTP subrequests section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1967 diff changeset	5291
1969 275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5292 <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	5293
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5294 <para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5295 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	5296 <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	5297 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	5298 to the filter chain.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5299 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	5300 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	5301 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	5302 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	5303 to finish sending the output.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5304 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	5305 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	5306 </para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5307
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5308 <para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5309 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	5310 following <literal>rc</literal> values:
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5311 </para>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5312
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5313 <list type="bullet">
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5314
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5315 <listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5316 <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	5317 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	5318 reaches zero.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5319 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	5320 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5321
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5322 <listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5323 <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	5324 (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	5325 finalization.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5326 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	5327 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5328
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5329 <listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5330 <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	5331 <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	5332 <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	5333 finalization.
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5334 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	5335 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	5336 <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	5337 configured for the code
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5338 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5339
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5340 <listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5341 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	5342 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	5343 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	5344 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	5345 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	5346 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	5347 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	5348 </listitem>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5349
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5350 </list>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5351
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5352 </section>
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5353
275c928ab386 The HTTP request finalization section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1968 diff changeset	5354
1970 a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5355 <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	5356
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5357 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5358 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	5359 <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	5360 <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	5361 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	5362 <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	5363 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	5364 body.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5365 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	5366 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	5367 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5368
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5369 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5370 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	5371 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	5372 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	5373 <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	5374 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	5375 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5376
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5377 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5378 The function
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5379 <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	5380 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	5381 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	5382 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	5383 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	5384 The function
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5385 <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	5386 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	5387 <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	5388 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	5389 chain.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5390 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	5391 <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	5392 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	5393 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5394
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5395 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5396 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	5397 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5398
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5399 <programlisting>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5400 ngx_int_t
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5401 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	5402 {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5403 ngx_int_t rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5404
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5405 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	5406
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5407 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	5408 /* error */
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5409 return rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5410 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5411
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5412 return NGX_DONE;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5413 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5414
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5415
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5416 void
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5417 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	5418 {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5419 off_t len;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5420 ngx_buf_t *b;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5421 ngx_int_t rc;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5422 ngx_chain_t *in, out;
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 if (r->request_body == NULL) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5425 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	5426 return;
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
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5429 len = 0;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5430
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5431 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	5432 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	5433 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5434
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5435 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	5436 if (b == NULL) {
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5437 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	5438 return;
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 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	5442 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	5443 b->last_in_chain = 1;
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 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	5446 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	5447
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5448 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	5449
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5450 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	5451 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	5452 return;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5453 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5454
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5455 out.buf = b;
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5456 out.next = NULL;
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 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	5459
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5460 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	5461 }
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5462 </programlisting>
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 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5465 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	5466 </para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5467
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5468 <list type="bullet">
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 <listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5471 <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	5472 buffer
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5473 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5474
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5475 <listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5476 <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	5477 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	5478 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5479
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5480 <listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5481 <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	5482 right after creation.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5483 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	5484 </listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5485
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5486 <listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5487 <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	5488 request is finalized.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5489 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	5490 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	5491 </listitem>
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 <listitem>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5494 <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	5495 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	5496 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	5497 </listitem>
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_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	5501 log level
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_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	5506 buffering
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 </list>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5510
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5511 <para>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5512 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	5513 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	5514 In this mode, after calling
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5515 <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	5516 <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	5517 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	5518 <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	5519 called.
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5520 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	5521 <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	5522 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	5523 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	5524 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	5525 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	5526 </para>
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 </section>
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5529
a1d29eda04b6 The HTTP request body section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1969 diff changeset	5530
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5531 <section name="Response" id="http_response">
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5532
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5533 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5534 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	5535 the optional response body.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5536 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	5537 written to the client socket.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5538 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	5539 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	5540 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5541
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5542
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5543 <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	5544
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5545 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5546 Output header is sent by the function
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5547 <literal>ngx_http_send_header(r)</literal>.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5548 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	5549 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	5550 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	5551 <literal>r->headers_out</literal>.
1971 5fb870087b76 Fixed typo and removed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1970 diff changeset	5552 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	5553 <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	5554 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	5555 unknown.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5556 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	5557 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	5558 appended.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5559 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5560
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5561 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5562 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5563 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	5564 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5565 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5566 ngx_table_elt_t *h;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5567
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5568 /* send header */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5569
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5570 r->headers_out.status = NGX_HTTP_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5571 r->headers_out.content_length_n = 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5572
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5573 /* X-Foo: foo */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5574
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5575 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	5576 if (h == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5577 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5578 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5579
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5580 h->hash = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5581 ngx_str_set(&h->key, "X-Foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5582 ngx_str_set(&h->value, "foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5583
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5584 rc = ngx_http_send_header(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5585
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5586 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	5587 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5588 }
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 /* send body */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5591
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5592 ...
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 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5595
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5596 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5597
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 <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	5600
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5601 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5602 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	5603 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	5604 <literal>ngx_http_top_header_filter</literal>.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5605 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	5606 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	5607 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	5608 <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	5609 <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	5610 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5611
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5612 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5613 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	5614 <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	5615 time.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5616 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	5617 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	5618 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5619
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5620 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5621 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	5622 "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	5623 </para>
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 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5626 #include <ngx_config.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5627 #include <ngx_core.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5628 #include <ngx_http.h>
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5631 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	5632 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	5633
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5634
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5635 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	5636 NULL, /* preconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5637 ngx_http_foo_header_filter_init, /* postconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5638
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5639 NULL, /* create main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5640 NULL, /* init main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5641
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5642 NULL, /* create server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5643 NULL, /* merge server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5644
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5645 NULL, /* create location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5646 NULL /* merge location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5647 };
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5650 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	5651 NGX_MODULE_V1,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5652 &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	5653 NULL, /* module directives */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5654 NGX_HTTP_MODULE, /* module type */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5655 NULL, /* init master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5656 NULL, /* init module */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5657 NULL, /* init process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5658 NULL, /* init thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5659 NULL, /* exit thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5660 NULL, /* exit process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5661 NULL, /* exit master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5662 NGX_MODULE_V1_PADDING
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5665
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5666 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	5667
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5668
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5669 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5670 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	5671 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5672 ngx_table_elt_t *h;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5673
1971 5fb870087b76 Fixed typo and removed trailing spaces. Vladimir Homutov <vl@nginx.com> parents: 1970 diff changeset	5674 /*
1960 9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5675 * 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	5676 * to every HTTP 200 response
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 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	5680 return ngx_http_next_header_filter(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5681 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5682
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5683 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	5684 if (h == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5685 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5686 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5687
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5688 h->hash = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5689 ngx_str_set(&h->key, "X-Foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5690 ngx_str_set(&h->value, "foo");
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5691
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5692 return ngx_http_next_header_filter(r);
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5696 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5697 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	5698 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5699 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	5700 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	5701
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5702 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5703 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5704 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5705
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5706 </section>
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 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5709
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5710
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5711 <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	5712
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5713 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5714 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	5715 <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	5716 The function can be called multiple times.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5717 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	5718 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	5719 </para>
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 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5722 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	5723 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	5724 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	5725 of the output.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5726 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	5727 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	5728 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5729
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5730 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5731 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5732 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	5733 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5734 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5735 ngx_buf_t *b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5736 ngx_chain_t out;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5737
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5738 /* send header */
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 r->headers_out.status = NGX_HTTP_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5741 r->headers_out.content_length_n = 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5742
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5743 rc = ngx_http_send_header(r);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5744
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5745 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	5746 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5747 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5748
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5749 /* send body */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5750
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5751 b = ngx_calloc_buf(r->pool);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5752 if (b == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5753 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5754 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5755
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5756 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	5757 b->last_in_chain = 1;
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 b->memory = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5760
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5761 b->pos = (u_char *) "foo";
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5762 b->last = b->pos + 3;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5763
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5764 out.buf = b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5765 out.next = NULL;
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 return ngx_http_output_filter(r, &out);
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 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5770
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5771 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5772
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 <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	5775
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5776 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5777 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	5778 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	5779 <literal>ngx_http_top_body_filter</literal>.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5780 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	5781 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	5782 </para>
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 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5785 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	5786 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	5787 the next handler.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5788 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	5789 incoming chain belong to the caller.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5790 They should never be reused or changed.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5791 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	5792 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	5793 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	5794 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	5795 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5796
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5797 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5798 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	5799 body bytes.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5800 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	5801 used in the access log.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5802 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5803
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5804 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5805 #include <ngx_config.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5806 #include <ngx_core.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5807 #include <ngx_http.h>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5808
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5809
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5810 typedef struct {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5811 off_t count;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5812 } ngx_http_counter_filter_ctx_t;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5813
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5814
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5815 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	5816 ngx_chain_t *in);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5817 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	5818 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	5819 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	5820 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	5821
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5822
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5823 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	5824 ngx_http_counter_add_variables, /* preconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5825 ngx_http_counter_filter_init, /* postconfiguration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5826
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5827 NULL, /* create main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5828 NULL, /* init main configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5829
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5830 NULL, /* create server configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5831 NULL, /* merge server configuration */
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 NULL, /* create location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5834 NULL /* merge location configuration */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5835 };
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5836
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 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	5839 NGX_MODULE_V1,
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5840 &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	5841 NULL, /* module directives */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5842 NGX_HTTP_MODULE, /* module type */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5843 NULL, /* init master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5844 NULL, /* init module */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5845 NULL, /* init process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5846 NULL, /* init thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5847 NULL, /* exit thread */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5848 NULL, /* exit process */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5849 NULL, /* exit master */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5850 NGX_MODULE_V1_PADDING
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5853
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5854 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	5855
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5856 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	5857
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 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5860 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	5861 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5862 ngx_chain_t *cl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5863 ngx_http_counter_filter_ctx_t *ctx;
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 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	5866 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5867 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	5868 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5869 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5870 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5871
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5872 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	5873 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5874
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5875 for (cl = in; cl; cl = cl->next) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5876 ctx->count += ngx_buf_size(cl->buf);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5877 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5878
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5879 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	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_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5884 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	5885 uintptr_t data)
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 u_char *p;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5888 ngx_http_counter_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5889
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5890 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	5891 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5892 v->not_found = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5893 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5894 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5895
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5896 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	5897 if (p == 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 v->data = p;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5902 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	5903 v->valid = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5904 v->no_cacheable = 0;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5905 v->not_found = 0;
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 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5908 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5909
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 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5912 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	5913 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5914 ngx_http_variable_t *var;
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 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	5917 if (var == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5918 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5919 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5920
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5921 var->get_handler = ngx_http_counter_variable;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5922
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5923 return NGX_OK;
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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5926
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5927 static ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5928 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	5929 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5930 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	5931 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	5932
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5933 return NGX_OK;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5934 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5935 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5936
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5937 </section>
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 <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	5941
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5942 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5943 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	5944 filters order.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5945 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	5946 modules.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5947 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	5948 other filters.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5949 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	5950 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	5951 registered.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5952 </para>
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 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5955 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	5956 modules is provided by nginx.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5957 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	5958 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	5959 module's configuration.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5960 </para>
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 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5963 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	5964 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	5965 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5966
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5967 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5968 ngx_module_type=HTTP_AUX_FILTER
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5969 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	5970 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	5971
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5972 . auto/module
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5973 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5974
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5975 </section>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5976
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5977
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5978 <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	5979
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5980 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5981 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	5982 allocated buffers.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5983 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	5984 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	5985 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	5986 These buffers can be reused.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	5987 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	5988 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	5989 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	5990 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	5991 (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	5992 <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	5993 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	5994 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	5995 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	5996 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	5997 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	5998 <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	5999 this.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6000 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	6001 <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	6002 <literal>busy</literal> to <literal>free</literal>.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6003 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	6004 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	6005 </para>
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 <para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6008 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	6009 incoming buffer.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6010 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	6011 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	6012 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	6013 beyond the scope of this section.
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6014 </para>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6015
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6016 <programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6017 typedef struct {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6018 ngx_chain_t *free;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6019 ngx_chain_t *busy;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6020 } ngx_http_foo_filter_ctx_t;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6021
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6022
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6023 ngx_int_t
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6024 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	6025 {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6026 ngx_int_t rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6027 ngx_buf_t *b;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6028 ngx_chain_t cl, tl, out, *ll;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6029 ngx_http_foo_filter_ctx_t *ctx;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6030
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6031 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	6032 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6033 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	6034 if (ctx == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6035 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6036 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6037
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6038 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	6039 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6040
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6041 /* 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	6042
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6043 ll = &out;
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 for (cl = in; cl; cl = cl->next) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6046
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6047 /* 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	6048
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6049 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	6050 if (tl == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6051 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6052 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6053
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6054 b = tl->buf;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6055 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	6056 b->memory = 1;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6057 b->pos = (u_char *) "foo";
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6058 b->last = b->pos + 3;
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 *ll = tl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6061 ll = &tl->next;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6062
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6063 /* append the next incoming buffer */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6064
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6065 tl = ngx_alloc_chain_link(r->pool);
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6066 if (tl == NULL) {
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6067 return NGX_ERROR;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6068 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6069
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6070 tl->buf = cl->buf;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6071 *ll = tl;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6072 ll = &tl->next;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6073 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6074
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6075 *ll = NULL;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6076
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6077 /* send the new chain */
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6078
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6079 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	6080
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6081 /* update "busy" and "free" chains for reuse */
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 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	6084 (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
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6086 return rc;
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6087 }
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6088 </programlisting>
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6089
9550ea66abdd HTTP response section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1959 diff changeset	6090 </section>
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
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6093 <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	6094
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6095 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6096 The
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6097 <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	6098 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	6099 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	6100 such as HTTP or FastCGI.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6101 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	6102 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	6103 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6104
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6105 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6106 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	6107 <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	6108 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	6109 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	6110 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	6111 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	6112 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	6113 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6114
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6115 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6116 The
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6117 <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	6118 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	6119 <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	6120 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	6121 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	6122 for example,
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6123 <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	6124 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	6125 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	6126 <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	6127 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	6128 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6129 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	6130 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	6131 void **srv_conf;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6132
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6133 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	6134
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6135 ngx_uint_t flags;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6136 ngx_str_t host;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6137 u_char *file_name;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6138 ngx_uint_t line;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6139 in_port_t port;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6140 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	6141
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6142 #if (NGX_HTTP_UPSTREAM_ZONE)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6143 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	6144 #endif
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6145 };
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6146 </programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6147
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6148 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6149
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6150 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6151 <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	6152 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6153
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6154 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6155 <literal>servers</literal> — array of
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6156 <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	6157 <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	6158 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	6159 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6160
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6161 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6162 <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	6163 (configured as parameters of
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6164 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	6165 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	6166
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6167 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6168
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6169 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6170 <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	6171 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	6172 <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	6173 (FastCGI, SCGI, etc.)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6174 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6175
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6176 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6177 <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	6178 is supported
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
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 <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	6183 is supported
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6184 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6185
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6186 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6187 <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	6188 “<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	6189 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6190
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6191 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6192 <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	6193 is supported
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6194 </listitem>
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 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6197 <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	6198 is supported
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6199 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6200
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6201 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6202 <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	6203 is supported
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6204 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6205
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6206 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6207
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>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	6212 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6213
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6214 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6215 <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	6216 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	6217 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6218
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6219 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6220 <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	6221 upstreams
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6222 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6223
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6224 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6225 <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	6226 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6227
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 <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	6230 initializing upstream configuration:
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6231
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6232 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6233 typedef struct {
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6234 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	6235 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	6236 void *data;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6237 } ngx_http_upstream_peer_t;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6238 </programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6239 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	6240 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	6241 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	6242 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	6243 <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	6244
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6245 <list type="bullet">
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 <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	6248 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	6249 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	6250 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	6251 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	6252 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	6253 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6254
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 <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	6257 <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	6258 <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	6259 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	6260 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	6261 deal with server selection.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6262 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6263 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6264
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6265 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6266 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6267 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6268
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6269 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6270 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	6271 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	6272 The method is taken from the
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6273 <literal>ngx_http_upstream_peer_t.peer</literal> object
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6274 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	6275 <programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6276 struct ngx_peer_connection_s {
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6277 [...]
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6278
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6279 struct sockaddr *sockaddr;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6280 socklen_t socklen;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6281 ngx_str_t *name;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6282
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6283 ngx_uint_t tries;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6284
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6285 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	6286 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	6287 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	6288 void *data;
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6289
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6290 #if (NGX_SSL \|\| NGX_COMPAT)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6291 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	6292 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	6293 #endif
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6294
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6295 [..]
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6296 };
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6297 </programlisting>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6298
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6299 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	6300
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6301 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6302 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6303 <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	6304 <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	6305 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	6306 </listitem>
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 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6309 <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	6310 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	6311 configuration.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6312 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	6313 (see below)
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6314 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6315
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6316 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6317 <literal>tries</literal> — allowed
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6318 <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	6319 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	6320 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6321
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6322 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6323 <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	6324 <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	6325 - 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	6326 </listitem>
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 </list>
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 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6331
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6332 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6333 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	6334 <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	6335 <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	6336 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	6337 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	6338 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6339
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6340 <para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6341
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6342 <list type="bullet">
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 <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	6345 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	6346 its address.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6347 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	6348 <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	6349 <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	6350 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	6351
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6352 <list type="bullet">
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6353
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6354 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6355 <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	6356 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6357
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6358 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6359 <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	6360 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6361
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6362 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6363 <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	6364 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	6365 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	6366 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	6367 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	6368 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6369
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6370 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6371 <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	6372 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	6373 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	6374 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6375
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6376 <!--
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6377 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6378 <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	6379 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	6380 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	6381 </listitem>
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
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6384 </list>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6385
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6386 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6387
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6388 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6389 <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	6390 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	6391 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	6392 completion.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6393 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	6394 <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	6395 <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	6396 <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	6397 (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	6398 <literal>NGX_PEER_KEEPALIVE</literal>.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6399 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	6400 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6401
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6402 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6403 <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	6404 in the OSS version.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6405 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6406
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6407 <listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6408 <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	6409 <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	6410 — 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	6411 servers.
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6412 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	6413 </listitem>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6414
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6415 </list>
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 </para>
c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6418
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6419 </section>
7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6420
1939 c1b0169e8f54 Added the "Load balancing" section of the development guide. Vladimir Homutov <vl@nginx.com> parents: 1936 diff changeset	6421 </section>
1929 7f290929b32d HTTP section of the development guide. Roman Arutyunyan <arut@nginx.com> parents: 1928 diff changeset	6422
1899 b86cfece30c3 Added development guide. Vladimir Homutov <vl@nginx.com> parents: diff changeset	6423 </article>

Mercurial > hg > nginx-site

annotate xml/en/docs/dev/development_guide.xml @ 1993:98b713b0a9fa